# 顺影 AIGC · 开放 API 文档

> 版本：v1（草案 0.1）
> 状态：**接口契约已定，服务端网关尚未实现**。本文档是给未来的开放平台和第三方开发者看的契约，也是我们自己服务端的开发依据。标了「待实现」的地方目前还不可用。

---

## 1. 这份 API 是干什么的

顺影 AIGC 提供图片与视频的生成能力。开放 API 让第三方用自己的账号、自己的界面来调用：

- 查模型与价格
- 提交视频 / 图片生成任务（异步、可批量）
- 查询任务进度、取结果、取消任务
- 上传与复用参考素材
- 接收任务完成回调

**设计目标**：第三方完全可以用这套 API 搭一个和官方工作台一样的东西出来——这是刻意的，官方前端也只调这套接口。

---

## 2. 基础约定

| 项 | 约定 |
| --- | --- |
| Base URL | `https://api.shunyingaigc.com/v1`（示例域名，落地时以控制台为准） |
| 协议 | 仅 HTTPS，TLS 1.2+ |
| 编码 | 请求与响应均为 `application/json; charset=utf-8` |
| 认证 | `Authorization: Bearer sk_live_xxx` |
| 路径风格 | REST，资源名复数，动作用子路径 |
| 时间 | ISO 8601，UTC，例：`2026-11-15T02:07:43Z` |
| ID | 带前缀的字符串：`tsk_` 任务、`bat_` 批次、`ast_` 素材、`req_` 请求 |
| 版本 | 路径里的 `/v1`。破坏性变更升 `/v2`，`/v1` 至少再维护 12 个月 |

所有响应都带 `X-Request-Id`，排查问题时把它给我们。

---

## 3. 认证与密钥

在控制台「API 密钥」里创建，只在创建时显示一次明文，服务端只存哈希。

```
Authorization: Bearer sk_live_7f3c9a...
```

- `sk_live_` 生产、`sk_test_` 沙箱（沙箱不出真片、不扣积分）
- 密钥带作用域：`video:write`、`image:write`、`task:read`、`asset:write`
- 支持多个密钥并行，便于分环境、分团队；可单独吊销
- **密钥只能放服务端**。出现在浏览器、App 包体、公开仓库里的密钥视为已泄露，我们会自动禁用

> 现在官方前端把上游 Key 存在浏览器可读的表里，这是过渡方案。开放 API 之后，第三方只拿我们的 key，上游 key 永远留在我们服务端。

---

## 4. 计费与额度

- 单位是**积分**，视频按秒、图片按张
- 提交时**预扣**，成功按实际结算，失败全额退回
- 余额不足直接拒绝（`402 insufficient_credits`），不会进入排队
- 每个任务在响应里都带 `credits_reserved` / `credits_charged`，便于对账
- 批量提交（`count > 1`）按条分别预扣

查询余额：

```
GET /v1/account
```

```json
{
  "id": "acc_1024",
  "name": "张三的工作台",
  "credits": 1560,
  "credits_reserved": 120,
  "concurrency_limit": 8,
  "rate_limit_per_minute": 60
}
```

---

## 5. 模型

```
GET /v1/models
```

不带参数返回全部；`?kind=video` 或 `?kind=image` 过滤。

```json
{
  "data": [
    {
      "id": "seedance-2",
      "kind": "video",
      "name": "Seedance 2.0",
      "series": "即梦",
      "vendor": "字节即梦",
      "status": "available",
      "durations": [5, 10, 12],
      "qualities": ["480P", "720P", "1080P"],
      "aspect_ratios": ["16:9", "9:16", "1:1", "4:3", "3:4"],
      "modes": ["i2v", "t2v"],
      "max_reference_images": 9,
      "price": { "unit": "second", "credits": 6 },
      "avg_latency_seconds": 168
    },
    {
      "id": "seedream-3",
      "kind": "image",
      "name": "Seedream 3.0",
      "status": "available",
      "aspect_ratios": ["1:1", "3:4", "4:3", "16:9", "9:16"],
      "max_reference_images": 4,
      "price": { "unit": "image", "credits": 6 },
      "avg_latency_seconds": 16
    }
  ]
}
```

字段说明：

- `status`：`available` 可用 / `degraded` 降级（能出片但慢或成功率低）/ `offline` 暂不可用
- `durations`：**这个模型允许的秒数，只能从这里选**，传别的值会 `400 unsupported_duration`
- `price`：计费口径。`credits × duration × count` 是预计消耗
- `avg_latency_seconds`：近期平均耗时，用来决定轮询节奏

`GET /v1/models/{id}` 返回单个模型，字段同上。

---

## 6. 提交视频任务

```
POST /v1/videos
```

### 请求体

```json
{
  "model": "seedance-2",
  "prompt": "镜头缓慢推近，阳光从窗外斜射进来，尘埃在光里慢慢飘动",
  "reference_images": [
    "https://your-cdn.com/a.jpg",
    "https://your-cdn.com/b.jpg"
  ],
  "duration": 5,
  "quality": "720P",
  "aspect_ratio": "16:9",
  "count": 1,
  "mode": "i2v",
  "webhook_url": "https://your-app.com/hooks/shunying"
}
```

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `model` | 是 | 模型 id，见 `/v1/models` |
| `prompt` | 是 | 1–300 字 |
| `reference_images` | 视模式 | `i2v` / `kf` 必填；`t2v` 可省略。最多 9 张，公网可访问的 URL 或 `/v1/assets` 返回的 `asset_id` |
| `duration` | 是 | 必须落在该模型的 `durations` 里 |
| `quality` | 否 | 默认取模型第一个 |
| `aspect_ratio` | 否 | 默认 `16:9` |
| `count` | 否 | 1–4，同一提示词出几条，按条计费，默认 1 |
| `mode` | 否 | `i2v` 图生视频 / `t2v` 文生视频 / `kf` 首尾帧，默认按是否有参考图推断 |
| `webhook_url` | 否 | 完成回调地址，见第 10 节 |
| `metadata` | 否 | 自定义键值，原样带回，最长 2KB |

`mode: "kf"` 时 `reference_images` 必须是 2 张（首帧、尾帧）。

### 响应 `202 Accepted`

```json
{
  "batch_id": "bat_9f21c0",
  "tasks": [
    {
      "id": "tsk_7a3d11",
      "status": "queued",
      "model": "seedance-2",
      "duration": 5,
      "count_index": 1,
      "credits_reserved": 30
    }
  ]
}
```

一次提交 N 条就返回 N 个 `task`，各自独立排队、独立结算。

### 幂等

带 `Idempotency-Key: <uuid>`，24 小时内相同 key 返回第一次的结果，不会重复扣费。**网络超时重试时必须带**。

---

## 7. 查询任务

```
GET /v1/tasks/{task_id}
```

```json
{
  "id": "tsk_7a3d11",
  "batch_id": "bat_9f21c0",
  "kind": "video",
  "status": "succeeded",
  "progress": 100,
  "stage": "完成",
  "model": "seedance-2",
  "prompt": "镜头缓慢推近…",
  "duration": 5,
  "quality": "720P",
  "aspect_ratio": "16:9",
  "reference_images": ["https://your-cdn.com/a.jpg"],
  "result": {
    "type": "video",
    "url": "https://cdn.shunyingaigc.com/out/tsk_7a3d11.mp4",
    "thumbnail_url": "https://cdn.shunyingaigc.com/out/tsk_7a3d11.jpg",
    "duration": 5,
    "width": 1280,
    "height": 720,
    "bytes": 4823110
  },
  "credits_reserved": 30,
  "credits_charged": 30,
  "error": null,
  "created_at": "2026-11-15T02:07:43Z",
  "started_at": "2026-11-15T02:07:45Z",
  "completed_at": "2026-11-15T02:10:31Z",
  "metadata": { "user_id": "u_88" }
}
```

### 状态机

```
queued ──► running ──► succeeded
   │           │
   └───────────┴────► failed
   │
   └───────────────► canceled
```

| 状态 | 含义 | 是否终态 |
| --- | --- | --- |
| `queued` | 已受理，排队中（未开始计费） | 否 |
| `running` | 生成中，`progress` 0–100 | 否 |
| `succeeded` | 完成，`result.url` 可用 | 是 |
| `failed` | 失败，看 `error`，积分已退回 | 是 |
| `canceled` | 已取消，积分已退回 | 是 |

### 轮询建议

- 提交后 3 秒开始查，之后按 `Retry-After` 响应头走（我们会给 3–10 秒的建议值）
- 或者直接用 Webhook，轮询只作兜底
- 视频超时上限 8 分钟，图片 2 分钟；超时置 `failed` 并退款
- 结果 URL 有效期 **24 小时**，过期请提前转存到你自己的存储

批量查询：

```
GET /v1/tasks?ids=tsk_7a3d11,tsk_7a3d12
```

---

## 8. 取消任务

```
POST /v1/tasks/{task_id}/cancel
```

- `queued` 直接取消，全额退
- `running` 尝试取消，上游已出片则可能失败（返回 `409 cannot_cancel`）
- 已终态返回 `409 already_finished`

```json
{ "id": "tsk_7a3d11", "status": "canceled", "credits_refunded": 30 }
```

---

## 9. 参考素材

三种传法，任选：

1. 直接给公网可访问的 URL（我们会拉取并落盘到你名下）
2. `multipart/form-data` 上传到 `POST /v1/assets`
3. 先要一个预签名地址，前端直传对象存储：

```
POST /v1/assets/presign
{ "filename": "a.jpg", "content_type": "image/jpeg", "bytes": 820311 }

→ { "asset_id": "ast_5c1", "upload_url": "https://...", "expires_in": 600, "method": "PUT" }
```

上传完 `POST /v1/assets/{asset_id}/complete` 确认，之后可在 `reference_images` 里直接写 `asset_id`。

- 支持 JPG / PNG / WebP，单张 ≤ 10MB
- 素材存在你账号下，默认保留 30 天，可复用
- `GET /v1/assets` 分页列出，`DELETE /v1/assets/{id}` 删除

---

## 10. Webhook 回调

`webhook_url` 可以按任务传，也可以在控制台配默认地址。

### 事件体

```json
{
  "event": "task.succeeded",
  "id": "evt_33ab",
  "created_at": "2026-11-15T02:10:31Z",
  "data": {
    "id": "tsk_7a3d11",
    "status": "succeeded",
    "result": { "type": "video", "url": "https://...", "duration": 5 },
    "credits_charged": 30
  }
}
```

事件类型：`task.succeeded`、`task.failed`、`task.canceled`。

### 验证签名

```
X-Sy-Signature: t=1731640231,v1=6f2c9d...
```

```
signed_payload = t + "." + raw_body
v1 = HMAC_SHA256(webhook_secret, signed_payload) 的 hex
```

校验步骤：取 `t` 与 `v1`，用同样的算法算一遍，常量时间比较；`t` 与当前时间差超过 5 分钟视为过期，直接拒。

### 重试

返回 2xx 视为成功。失败按 `1min → 5min → 30min → 2h → 6h` 重试 5 次，之后放弃。**你的接口要幂等**（同一个 `evt_id` 只处理一次）。

---

## 11. 错误

统一信封：

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "积分不足：本次需要 30，当前可用 12",
    "request_id": "req_88af1",
    "param": "duration"
  }
}
```

| HTTP | code | 含义 |
| --- | --- | --- |
| 400 | `invalid_request` | 参数缺失或格式不对 |
| 400 | `unsupported_duration` | 时长不在该模型的 `durations` 里 |
| 400 | `unsupported_quality` | 画质不支持 |
| 400 | `reference_image_required` | 图生视频没给参考图 |
| 401 | `unauthorized` | key 缺失、无效或已吊销 |
| 403 | `forbidden` | key 缺少对应作用域 |
| 402 | `insufficient_credits` | 积分不足 |
| 404 | `task_not_found` | 任务不存在或不属于你 |
| 409 | `cannot_cancel` | 已出片，取消失败 |
| 409 | `already_finished` | 已终态 |
| 413 | `payload_too_large` | 请求体或素材超限 |
| 422 | `content_rejected` | 内容审核未通过 |
| 429 | `rate_limited` | 超出频率或并发，看 `Retry-After` |
| 502 | `upstream_error` | 上游平台异常，积分已退回 |
| 503 | `model_unavailable` | 该模型暂时不可用 |

`429` 与 `503` 可以退避重试，其它 4xx 不要重试。

---

## 12. 限流与并发

| 维度 | 默认 | 
| --- | --- |
| 请求频率 | 60 次/分钟 |
| 并发任务 | 8 个（视频 + 图片合计） |
| 单次批量 | `count` ≤ 4 |
| 单账号排队上限 | 40 个 |

响应头：

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1731640290
```

超额返回 `429`，`Retry-After` 给秒数。并发和频率都可以在控制台申请提额。

---

## 13. 快速开始

### 13.1 图生视频（curl）

```bash
# 1. 提交
curl -X POST https://api.shunyingaigc.com/v1/videos \
  -H "Authorization: Bearer $SY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "seedance-2",
    "prompt": "镜头缓慢推近，阳光从窗外斜射进来，尘埃在光里慢慢飘动",
    "reference_images": ["https://your-cdn.com/a.jpg"],
    "duration": 5,
    "quality": "720P",
    "aspect_ratio": "16:9",
    "count": 1
  }'

# 2. 轮询
curl https://api.shunyingaigc.com/v1/tasks/tsk_7a3d11 \
  -H "Authorization: Bearer $SY_KEY"
```

### 13.2 Node

```js
const BASE = 'https://api.shunyingaigc.com/v1'
const KEY = process.env.SY_KEY

async function generate({ prompt, images, model = 'seedance-2', duration = 5 }) {
  const submit = await fetch(`${BASE}/videos`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      model, prompt, duration,
      quality: '720P',
      aspect_ratio: '16:9',
      reference_images: images
    })
  })
  if (!submit.ok) throw new Error((await submit.json()).error.message)
  const { tasks } = await submit.json()

  for (;;) {
    await new Promise(r => setTimeout(r, 4000))
    const r = await fetch(`${BASE}/tasks/${tasks[0].id}`, {
      headers: { Authorization: `Bearer ${KEY}` }
    })
    const t = await r.json()
    if (t.status === 'succeeded') return t.result.url
    if (t.status === 'failed') throw new Error(t.error.message)
  }
}
```

### 13.3 Python

```python
import os, time, requests

BASE = "https://api.shunyingaigc.com/v1"
H = {"Authorization": f"Bearer {os.environ['SY_KEY']}"}

r = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "seedance-2",
    "prompt": "镜头缓慢推近，阳光从窗外斜射进来",
    "reference_images": ["https://your-cdn.com/a.jpg"],
    "duration": 5,
    "quality": "720P",
    "aspect_ratio": "16:9",
})
task = r.json()["tasks"][0]

while True:
    t = requests.get(f"{BASE}/tasks/{task['id']}", headers=H).json()
    if t["status"] == "succeeded":
        print(t["result"]["url"]); break
    if t["status"] == "failed":
        raise RuntimeError(t["error"]["message"])
    time.sleep(4)
```

---

## 14. 与官方前端的对应关系

官方工作台不走任何私有接口，它调的就是本文档的接口。对照表：

| 前端动作 | API |
| --- | --- |
| 模型条 / 模型广场 | `GET /v1/models` |
| 每行提示词提交 | `POST /v1/videos`，一行一次或一个 `count` |
| 批量粘贴后提交 | 每行一次 `POST /v1/videos`，共享一个 `Idempotency-Key` 前缀 |
| 生成队列进度 | `GET /v1/tasks/{id}` |
| 生成记录 / 我的资产 | `GET /v1/tasks`、`GET /v1/assets` |
| 删除作品 | `DELETE /v1/tasks/{id}` |
| 图片生成 | `POST /v1/images` |

「时长由模型决定」「参考图最多 9 张」「出片条数 1–4」这些前端约束，服务端会再校验一遍——不要指望前端拦住非法值。

---

## 15. 上游适配层（我们内部用）

平台侧一个模型可以绑多条上游渠道，运行时按健康度选择。这就是 `video_providers` + `model_bindings` 两张表要做的事，也是开放 API 之后第三方不需要知道的部分。

上游适配器的契约（写新厂商时只实现这三个）：

```
submit(ctx)  → { upstream_task_id }
poll(id)     → { status, result_url, error }
normalize()  → queued | running | succeeded | failed
```

`field_map` 负责字段映射，接新平台不改代码：

```json
{
  "task_id": "data.task_id",
  "status": "data.status",
  "video_url": "data.video_url",
  "status_map": { "completed": "succeeded", "error": "failed" }
}
```

多 Key 池、失败熔断、预扣退款、`upstream_task_id` 唯一索引防重复回调——这些都在网关里做，不暴露给第三方。

---

## 16. 合规与内容安全

- 所有输入提示词与输出内容过审，未通过返回 `422 content_rejected`
- 生成结果带不可见水印与可追溯 ID
- 默认保留提示词与结果 30 天用于审计，可按账号关闭留存（仍保留计数与计费记录）
- 禁止用于生成违法、侵权、深度伪造他人形象的内容；违规账号直接封停，余额不退
- 面向公众提供服务需按《生成式人工智能服务管理暂行办法》完成算法备案

---

## 17. 变更记录

| 版本 | 日期 | 内容 |
| --- | --- | --- |
| 0.1 | 2026-11-15 | 初稿：认证、模型、视频/图片任务、素材、Webhook、错误码、限流 |

---

## 18. 待实现清单（服务端）

按依赖顺序，做完这些才谈得上「开放」：

1. 网关骨架：鉴权、路由、请求日志、`X-Request-Id`
2. 账号体系：API Key 的创建/吊销/作用域、余额与账本
3. `POST /v1/videos`、`POST /v1/images`：校验 → 预扣 → 落库 → 入队
4. 任务 worker：轮询上游、写状态、结算、触发 Webhook
5. `GET /v1/tasks`、取消、`DELETE`
6. 素材上传与预签名
7. 限流与并发控制
8. 控制台：密钥、用量、账单
9. 沙箱环境（`sk_test_`，不出真片）
