接口接入

网站本身就是这套接口的第一个使用者。你的 App、小程序或脚本用同一套接口， 能力完全一致，不存在「网页版专属功能」。

鉴权

三种凭证任选其一，服务端处理逻辑相同：

• Cookie：浏览器登录后自动携带，网页端用这个。
• Authorization: Bearer <token>：登录接口返回的 JWT，App 与小程序用这个。
• X-Api-Key: <key>：在账户页创建的密钥，服务端脚本用这个。需要专业及以上方案。

响应格式

所有接口返回统一信封：

// 成功
{ "ok": true, "data": { ... } }

// 失败
{ "ok": false, "error": { "code": "INSUFFICIENT_CREDITS", "message": "积分不足，请先补充积分" } }

主要接口

登录

POST /api/v1/auth/login
{ "email": "you@example.com", "password": "······" }

→ { "ok": true, "data": { "token": "eyJ...", "user": { ... } } }

上传素材

POST /api/v1/uploads
Content-Type: multipart/form-data
file: <二进制>

→ { "ok": true, "data": { "asset": { "id": "...", "url": "/uploads/...", "kind": "image" } } }

提交生成

POST /api/v1/tasks
{
  "mode": "i2v",                       // t2v | i2v | flf2v | ref2v | v2v
  "modelKey": "seedance-2-5",
  "prompt": "······",
  "params": {
    "resolution": "1080p",             // 480p | 720p | 1080p | 4k
    "ratio": "16:9",
    "duration": 5,
    "watermark": false,
    "cameraFixed": false,
    "generateAudio": true
  },
  "assets": { "firstFrameUrl": "/uploads/..." }
}

→ { "ok": true, "data": { "task": { "id": "...", "status": "QUEUED", ... }, "credits": 1710 } }

查询进度

GET /api/v1/tasks/{id}        // 单条，会主动同步一次上游状态
GET /api/v1/tasks?page=1      // 列表，会同步该用户全部未完成任务

status: PENDING | QUEUED | RUNNING | SUCCEEDED | FAILED | CANCELLED

建议 3 秒轮询一次，全部进入终态后停止。任务失败时积分会自动退回，refunded 字段可用于确认。

其他

• GET /api/v1/models — 模型能力矩阵与积分单价
• GET /api/v1/templates — 模板库
• GET /api/v1/credits — 余额与流水
• POST /api/v1/orders — 下单

错误码

• UNAUTHORIZED — 未登录或凭证失效
• INSUFFICIENT_CREDITS — 积分不足
• PLAN_LIMIT — 超出当前方案权益（分辨率、时长、水印）
• CONCURRENCY_LIMIT — 同时进行的任务数已达上限
• VALIDATION_ERROR — 参数不合法
• PROVIDER_ERROR — 上游生成服务异常，积分已退回