紫域 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

GET/api/v1/me

查询账号和剩余额度。

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

GET/api/v1/models

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

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

{
  "ok": true,
  "models": [{
    "id": "model_xxxxxxxxxxxxx",
    "name": "对外显示名称",
    "type": "video",
    "modes": ["i2v", "t2v"],
    "allowedDurations": [5, 10, 15],
    "allowedRatios": ["16:9", "9:16"],
    "assetLimits": {"image": 4, "video": 3, "audio": 1},
    "resolution": "720p"
  }]
}

字段	说明
`id`	模型 ID，提交任务时传入 `modelId`
`name`	模型对外显示名称
`type`	`video`、`image` 或 `text`
`modes`	支持模式：`i2v` 图生视频，`t2v` 文生视频，`t2i` 文生图
`cost`	每次任务扣除额度
`costPerSecond` / `durationCosts`	按秒或指定时长定价；非空时优先按对应规则计算
`allowedDurations`	允许的时长，空数组表示模型未额外限制
`allowedRatios`	允许的画面比例，空数组表示模型未额外限制
`allowedAssetTypes` / `assetLimits`	支持的素材类型和图片、视频、音频数量上限
`resolution`	后台配置的输出分辨率；空字符串表示未单独指定
`promptMaxLength`	提示词字符上限；`0` 表示未额外限制

POST/api/v1/uploads

上传参考素材。图片仅支持 JPG、PNG、WebP 静态图，不支持 GIF 动图；视频和音频会自动压缩到规则范围内。一次最多 10 个文件。

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 可以直接放入任务的 assets.image/video/audio。

POST/api/v1/jobs

提交生成任务。提交成功会立即扣除对应额度；如果任务最终失败，系统会按现有规则返还额度。

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

字段	是否必填	说明
`modelId`	否	来自 `GET /api/v1/models`；不传时使用后台默认的 API 可用模型
`mode`	是	`i2v`、`t2v`、`t2i`
`prompt`	是	生成提示词
`ratio`	否	`16:9`、`9:16`、`1:1`、`3:4`、`4:3`
`duration`	否	视频时长，例如 `5秒`、`10秒`
`assets`	否	参考素材，支持使用上传接口返回的 URL，也支持公网可访问 URL；图片 URL 不支持 GIF

GET/api/v1/jobs/{jobId}

查询单个任务。建议每 3 到 5 秒轮询一次，不要高频请求。返回的 previewUrl 是本站地址，下载时继续携带同一个 API Key。

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

任务状态

状态	说明
`queued`	排队中
`processing`	生成中
`completed`	已完成，读取 `previewUrl`
`failed`	失败，读取 `failureReason` 或 `message`

GET/api/v1/jobs?limit=50

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

错误码

HTTP	说明
`400`	请求参数或文件格式错误
`401`	API Key 缺失或无效
`402`	账号额度不足
`403`	账号已禁用
`404`	任务不存在
`429`	请求过于频繁
`500/502`	生成服务暂时异常
`503`	后台已暂时关闭对外 API 总开关

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