紫域 AI 对外接口文档

Base URL：https://ziyuai.vip

重要 API Key 只能放在对接方服务器里，不能写进网页前端或小程序前端。任务结果完成 24 小时后会清理，请及时下载保存。

最短调用流程

1. 获取账号的 API Key
2. GET /api/v1/models 获取可用模型
3. 可选：POST /api/v1/uploads 上传参考图片/视频/音频
4. POST /api/v1/jobs 提交生成任务
5. GET /api/v1/jobs/{jobId} 轮询任务结果

认证方式

所有 /api/v1 接口都需要 API Key。推荐使用 Bearer 方式：

Authorization: Bearer zyai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

也兼容：

X-API-Key: zyai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

查询账号及个人余额 user.credits。此字段不是企业可用余额；任务实际使用的额度类型与余额见提交响应的 billing.type、billing.credits。

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://ziyuai.vip/api/v1/me

获取当前允许第三方调用的实时模型目录。模型上下架或 API 权限变化后，以此接口返回为准；提交任务时使用返回的 id 作为 modelId。

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://ziyuai.vip/api/v1/models

{
  "ok": true,
  "models": [{
    "id": "zy_model_example",
    "name": "对外显示名称",
    "type": "video",
    "modes": ["i2v", "t2v"],
    "allowedDurations": [5, 10, 15],
    "allowedRatios": ["16:9", "9:16"],
    "durationMin": 5,
    "durationMax": 15,
    "allowedAssetTypes": ["image", "video", "audio"],
    "assetLimits": {"image": 4, "video": 3, "audio": 1},
    "capabilitiesByMode": {
      "i2v": {
        "allowedAssetTypes": ["image", "video", "audio"],
        "assetLimits": {"image": 4, "video": 3, "audio": 1}
      },
      "t2v": {
        "allowedAssetTypes": [],
        "assetLimits": {"image": 0, "video": 0, "audio": 0}
      }
    },
    "referencePolicy": "all-assets",
    "referenceSyntax": {"image": "@图片1", "video": "@视频1", "audio": "@音频1"},
    "resolution": "720p"
  }]
}

上传参考素材。图片仅支持 JPG、PNG、WebP 静态图，不支持 GIF 动图。一次最多 10 个文件；模型允许 30 张图片时，可分三批上传，再合并 URL 提交一个任务。上传批次不影响任务里的引用编号。

上传接口的 JSON 请求体上限为 64 MiB（包含 Base64 编码后的体积）；普通 JSON 接口为 2 MiB。文件还需符合格式、大小及所选模型的时长要求，自动处理不保证所有素材都可接受。

curl -X POST https://ziyuai.vip/api/v1/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{
      "type": "image",
      "name": "ref.png",
      "data": "data:image/png;base64,BASE64_CONTENT"
    }]
  }'

将返回的 assets[].url 包装为 {"url":"返回的链接"}，放入对应类型数组。不能把 URL 字符串直接当数组元素。也可使用无需登录即可下载的公网 HTTPS 链接。

音频必须是可正常解码的真实音频文件，不能只修改扩展名伪装格式。建议导出不含封面图片的纯音频，以减少不同生成服务的兼容性差异；内嵌封面并不等于文件损坏，也不能仅凭封面判断任务失败原因。

视频素材引用：统一标准

在提示词中使用以下写法，图片、视频、音频各自从 1 编号：

后续编号依次递增，按本次请求中同类型素材数组的顺序对应，不按文件名或上传批次。

提交几份，就逐一引用几份。漏引用或编号不存在，直接拒绝，不扣积分、不提交生成。不自动补引用，不自动设为首帧。

无素材的文生视频不写引用；生图任务不套用本节规则。

例：两张图片＋两段音频

画面参考@图片1和@图片2，第一个人物的声音参考@音频1，第二个人物的声音参考@音频2。

完整请求示例

替换示例中的模型 ID 和素材链接。素材类型、数量、时长及比例须符合所选模型的目录配置。

{
  "modelId": "zy_model_example", "mode": "i2v",
  "prompt": "让@图片1中的人物自然转头并微笑",
  "duration": "5秒", "ratio": "16:9",
  "assets": {"image": [{"url": "https://example.com/person.jpg"}], "video": [], "audio": []}
}

{
  "modelId": "zy_model_example", "mode": "i2v",
  "prompt": "让@图片1中的人物走入@图片2的场景，保持人物外观一致",
  "duration": "5秒", "ratio": "16:9",
  "assets": {"image": [{"url": "https://example.com/person.jpg"}, {"url": "https://example.com/scene.jpg"}], "video": [], "audio": []}
}

{
  "modelId": "zy_model_example", "mode": "i2v",
  "prompt": "让@图片1中的人物配合@音频1的节奏跳舞",
  "duration": "5秒", "ratio": "16:9",
  "assets": {"image": [{"url": "https://example.com/person.jpg"}], "video": [], "audio": [{"url": "https://example.com/music.mp3"}]}
}

{
  "modelId": "zy_model_example", "mode": "i2v",
  "prompt": "画面参考@图片1和@图片2，第一个人物的声音参考@音频1，第二个人物的声音参考@音频2",
  "duration": "5秒", "ratio": "16:9",
  "assets": {
    "image": [{"url": "https://example.com/person-one.jpg"}, {"url": "https://example.com/person-two.jpg"}],
    "video": [],
    "audio": [{"url": "https://example.com/voice-one.mp3"}, {"url": "https://example.com/voice-two.mp3"}]
  }
}

{
  "modelId": "zy_model_example", "mode": "i2v",
  "prompt": "让@图片1中的人物参考@视频1的动作运动，保持人物外观一致",
  "duration": "5秒", "ratio": "16:9",
  "assets": {"image": [{"url": "https://example.com/person.jpg"}], "video": [{"url": "https://example.com/motion.mp4"}], "audio": []}
}

{
  "modelId": "zy_model_example", "mode": "t2v",
  "prompt": "清晨的城市街道，镜头缓慢向前推进",
  "duration": "5秒", "ratio": "16:9",
  "assets": {"image": [], "video": [], "audio": []}
}

通过本地校验并受理后会预占对应积分，最终按任务状态结算或退还。HTTP 202 表示已受理，不是失败，也不表示生成完成；不要重新创建同一业务任务。

请务必使用幂等标识：每次业务任务生成一个稳定且唯一的 Idempotency-Key（或请求体中的 clientRequestId），网络超时后使用同一个标识重试。不要为同一次任务生成新的标识，否则可能创建重复任务并重复扣除额度。旧客户端不带标识仍可提交，但无法获得重试去重保护。

curl -X POST https://ziyuai.vip/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_20260819_0001" \
  -d '{
    "modelId": "zy_model_example",
    "mode": "i2v",
    "prompt": "让@图片1中的人物自然转头并微笑",
    "ratio": "16:9",
    "duration": "5秒",
    "clientRequestId": "order_20260819_0001",
    "assets": {
      "image": [{"url": "https://ziyuai.vip/uploads/asset_image_xxx.jpg"}],
      "video": [],
      "audio": []
    }
  }'

受理响应（HTTP 202，主要字段示例）

{
  "ok": true,
  "submitPending": true,
  "job": {"id": "abcd1234", "status": "queued", "cost": 100},
  "billing": {"type": "user", "credits": 900},
  "credits": 900
}

示例积分仅演示结构，不是任何模型报价。job.cost 为该任务积分，billing 为实际扣费账户；顶层 credits 是个人余额，不应作为企业余额显示。

同一标识、同一请求重试会返回已有任务（HTTP 200，idempotentReplay: true），不重复创建或扣费；同一标识换了请求内容返回 409。重试应复用完全相同的请求体，头部与请求体同时传标识时保持一致。

因本地校验失败（如漏引用）返回 400 时，任务未受理、未预占积分。修正请求内容后，请使用新的幂等标识提交。

查询单个任务。建议每 3 到 5 秒轮询一次；同时查询多个任务时控制总请求频率，遇到 429 应延长间隔。状态和结果位于 job 内，不在响应顶层。

查询响应 HTTP 200、ok: true 只表示查询成功；任务是否成功必须看 job.status。若为 failed，停止轮询生成状态并读取失败原因及退款字段，不要自动重新提交。

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://ziyuai.vip/api/v1/jobs/abcd1234

{
  "ok": true,
  "job": {
    "id": "abcd1234", "status": "completed", "progress": 100,
    "cost": 100,
    "previewUrl": "https://ziyuai.vip/uploads/result_example.mp4",
    "resultUrl": "https://ziyuai.vip/uploads/result_example.mp4"
  }
}

完成后读取 job.resultUrl 或 job.previewUrl 下载。返回的签名或静态结果链接可直接访问，无需再带 Key，支持 HEAD 和 Range；不要向第三方网站转发 API Key。

/api/results/... 签名链接约 1 小时过期，可重新查询任务获取新链接；/uploads/... 静态链接不使用该签名时效。两种链接都受结果文件完成后 24 小时清理规则约束，刷新链接不会延长文件保留时间。

也可通过 GET /api/v1/jobs/{jobId}/result 获取结果，但这个接口必须携带 API Key。

任务状态

查询最近任务列表，limit 最大 100。

错误码

{
  "ok": false,
  "error": "insufficient credits"
}