# 顺影 AIGC · 开放 API 文档

> 版本：v1
> 状态：**已上线，密钥自助发放**。登录后点「申请 API 密钥」立刻拿到，不需要审核、不需要等人工。第 3 节列出的是现在就能直接调用的接口；第 6–12 节是后续 v1 契约的设计稿，尚未上线。

---

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

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

- 提交视频 / 图片生成任务
- 查询任务进度、取结果、取消任务
- 用自己账户里的积分结算，消耗与官方工作台一致

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

---

## 2. 基础约定

| 项 | 约定 |
| --- | --- |
| Base URL | `https://shunying.cloud` |
| 协议 | 仅 HTTPS，TLS 1.2+ |
| 编码 | 请求与响应均为 `application/json; charset=utf-8` |
| 认证 | `Authorization: Bearer sk_sy_xxx`，或 `x-api-key: sk_sy_xxx` |
| 路径风格 | REST，资源名复数，动作用子路径 |
| 时间 | ISO 8601，UTC |
| ID | 任务 ID 为字符串，原样回传即可 |

---

## 3. 认证与密钥

### 3.1 怎么拿到密钥

登录网站 → 「开放 API」页面 → 点「申请 API 密钥」→ 立刻生成。

- **不用审核**，生成即生效
- 完整密钥**只显示一次**，请当场复制保存；之后只能看到前 8 位
- 每个账号最多同时保留 5 个，可随时吊销，吊销立即失效
- 密钥绑定你的积分账户：调多少扣多少，余额不足返回 `402`

```
Authorization: Bearer sk_sy_7f3c9a...
```

也支持放在 `x-api-key` 头里，方便浏览器端之外的客户端。

**密钥只能放服务端。** 写进前端代码、App 包体、公开仓库的密钥视为已泄露，请在页面里吊销并重新生成。

### 3.2 现在就能调的接口

| 方法 | 路径 | 说明 | 积分 |
| --- | --- | --- | --- |
| POST | `/api/gv2/video/tasks` | 提交视频任务（Seedance 2.5） | 600 / 条 |
| GET | `/api/gv2/video/tasks/{task_id}` | 查任务状态与结果 | 0 |
| POST | `/api/gv2/video/tasks/{task_id}/cancel` | 取消任务 | 0 |
| POST | `/api/gi/images/generations` | 提交图片生成，返回图片地址 | 2 / 2.5 每张 |
| POST | `/api/gi/images/edits` | 带参考图改图（multipart） | 2 / 2.5 每张 |
| POST | `/api/gv/tasks` | 提交视频任务（其余视频模型） | 30–60 / 条 |
| GET | `/api/gv/tasks/{task_id}` | 查任务状态与结果 | 0 |
| POST | `/api/gv/tasks/{task_id}/cancel` | 取消任务 | 0 |

提交成功即预扣积分；上游明确失败会自动全额退回，不需要你申请。

### 3.3 提交视频（Seedance 2.5）

```bash
curl -X POST https://shunying.cloud/api/gv2/video/tasks \
  -H "Authorization: Bearer $SY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-seedance-25",
    "prompt": "镜头缓慢推近，阳光从窗外斜射进来，尘埃在光里慢慢飘动",
    "resolution": "720p",
    "duration_seconds": 5,
    "ratio": "16:9",
    "assets": { "images": [{ "source_url": "https://your-cdn.com/a.jpg" }] }
  }'
```

返回：

```json
{ "task_id": "tsk_xxx", "status": "SUBMITTED", "next_poll_after_seconds": 5 }
```

字段说明：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `model` | 是 | 固定 `my-seedance-25` |
| `prompt` | 是 | 提示词 |
| `resolution` | 否 | `480p` / `720p`，默认 `720p` |
| `duration_seconds` | 否 | 4–30，默认 5 |
| `ratio` | 否 | `16:9` / `9:16` / `1:1` 等 |
| `assets.images` | 否 | 参考图，公网可读的 HTTPS 地址 |
| `assets.videos` | 否 | 参考视频，同上 |
| `assets.audios` | 否 | 参考音频，同上（带音频必须同时带图） |

### 3.4 查询任务

```bash
curl https://shunying.cloud/api/gv2/video/tasks/tsk_xxx \
  -H "Authorization: Bearer $SY_KEY"
```

```json
{
  "task_id": "tsk_xxx",
  "status": "PROCESSING",
  "progress_percent": 42,
  "result_url": null
}
```

| status | 含义 | 终态 |
| --- | --- | --- |
| `SUBMITTED` | 已受理，排队中 | 否 |
| `PROCESSING` | 生成中 | 否 |
| `REVIEW_REQUIRED` | 平台人工核对中，**不要重投** | 否 |
| `SUCCEEDED` | 完成，`result_url` 可用 | 是 |
| `FAILED` | 失败，看 `status_message`，积分已退回 | 是 |

轮询节奏：提交后 5 秒查一次，之后按返回的 `next_poll_after_seconds` 走，别密集刷。

`result_url` 指向本站的 `/api/gf2/...` 代理地址，**拿到就立刻转存到你自己的存储**——服务端重启后该地址会失效。

### 3.5 生成图片

```bash
curl -X POST https://shunying.cloud/api/gi/images/generations \
  -H "Authorization: Bearer $SY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5",
    "prompt": "雨后的东京街头，霓虹倒影，电影感",
    "n": 1,
    "size": "1024x1024"
  }'
```

返回 `{ "data": [{ "url": "https://..." }] }`，同步接口，一般 15–30 秒。

带参考图时改成 `multipart/form-data` 发到 `/api/gi/images/edits`，字段 `model` / `prompt` / `size` / `n`，参考图用同名字段 `image` 重复传。

可用模型与单价见下方第 4 节。

---

## 4. 计费与额度

- 单位是**积分**，1 积分 = 0.01 元
- 提交时**预扣**，上游明确失败或请求没到上游，全额自动退回
- 余额不足直接拒绝（`402 insufficient_credits`），不会进入排队

| 模型 | 类型 | 积分 |
| --- | --- | --- |
| `my-seedance-25` | 视频 | 600 / 条 |
| `my-seedance-2-fast` | 视频 | 60 / 条 |
| `my-h3-15s` / `my-h3-15s-portrait` | 视频 | 30 / 条 |
| `my-h3-20s` / `my-h3-20s-portrait` | 视频 | 35 / 条 |
| `my-h3-30s` / `my-h3-30s-portrait` | 视频 | 50 / 条 |
| `my-h3-first-last` / `my-h3-reference` | 视频 | 30 / 条 |
| `gpt-image-2` | 图片 | 2 / 张 |
| `gpt-image-2.5` / `2.6` / `2.6-flare` / `2.6-sunburst` | 图片 | 2.5 / 张 |

查询余额与最近流水：

```
GET /api/wallet
```

```json
{
  "balance": 1560,
  "ledger": [
    { "delta": -600, "balance": 960, "reason": "spend", "at": "2026-11-16T07:12:03Z" }
  ]
}
```

---

## 5. 模型清单

当前可用的站内模型 id（提交任务时 `model` 就填这个）：

| id | 类型 | 说明 | 积分 |
| --- | --- | --- | --- |
| `my-seedance-25` | 视频 | Seedance 2.5，4–30 秒，最高 1080P，可带参考图 / 视频 / 音频 | 600 |
| `my-seedance-2-fast` | 视频 | Seedance 2.0 快版 | 60 |
| `my-h3-15s` | 视频 | 15 秒，横版 | 30 |
| `my-h3-15s-portrait` | 视频 | 15 秒，竖版 | 30 |
| `my-h3-20s` | 视频 | 20 秒，横版 | 35 |
| `my-h3-20s-portrait` | 视频 | 20 秒，竖版 | 35 |
| `my-h3-30s` | 视频 | 30 秒，横版 | 50 |
| `my-h3-30s-portrait` | 视频 | 30 秒，竖版 | 50 |
| `my-h3-first-last` | 视频 | 首尾帧 | 30 |
| `my-h3-reference` | 视频 | 多图参考 | 30 |
| `gpt-image-2` | 图片 | 通用出图 | 2 |
| `gpt-image-2.5` | 图片 | 通用出图 | 2.5 |
| `gpt-image-2.6` | 图片 | 通用出图 | 2.5 |
| `gpt-image-2.6-flare` | 图片 | 光斑风格 | 2.5 |
| `gpt-image-2.6-sunburst` | 图片 | 放射光风格 | 2.5 |

模型随时会增减，价格以本表与页面上的模型广场为准。

---

## 6. 提交视频任务

> 以下第 6–12 节是后续 v1 契约的设计稿，**尚未上线**，字段名与上文的实际接口不同。请先用第 3 节的接口。

```
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
export SY_KEY=sk_sy_xxxxxxxx        # 页面里生成的密钥

# 1. 提交
curl -X POST https://shunying.cloud/api/gv2/video/tasks \
  -H "Authorization: Bearer $SY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-seedance-25",
    "prompt": "镜头缓慢推近，阳光从窗外斜射进来，尘埃在光里慢慢飘动",
    "resolution": "720p",
    "duration_seconds": 5,
    "ratio": "16:9"
  }'

# 2. 轮询（把 tsk_xxx 换成上一步返回的 task_id）
curl https://shunying.cloud/api/gv2/video/tasks/tsk_xxx \
  -H "Authorization: Bearer $SY_KEY"
```

### 13.2 Node

```js
const BASE = 'https://shunying.cloud'
const KEY = process.env.SY_KEY
const H = { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' }

async function makeVideo(prompt, images = []) {
  const res = await fetch(`${BASE}/api/gv2/video/tasks`, {
    method: 'POST',
    headers: H,
    body: JSON.stringify({
      model: 'my-seedance-25',
      prompt,
      resolution: '720p',
      duration_seconds: 5,
      ratio: '16:9',
      assets: { images: images.map(url => ({ source_url: url })) }
    })
  })
  const t = await res.json()
  if (!res.ok) throw new Error(t.error?.message || '提交失败')

  for (;;) {
    await new Promise(r => setTimeout(r, (t.next_poll_after_seconds || 5) * 1000))
    const s = await fetch(`${BASE}/api/gv2/video/tasks/${t.task_id}`, { headers: H }).then(r => r.json())
    if (s.status === 'SUCCEEDED') return s.result_url
    if (s.status === 'FAILED') throw new Error(s.status_message || '生成失败')
  }
}
```

### 13.3 Python

```python
import os, time, requests

BASE = "https://shunying.cloud"
H = {"Authorization": f"Bearer {os.environ['SY_KEY']}"}

r = requests.post(f"{BASE}/api/gv2/video/tasks", headers=H, json={
    "model": "my-seedance-25",
    "prompt": "镜头缓慢推近，阳光从窗外斜射进来",
    "resolution": "720p",
    "duration_seconds": 5,
    "ratio": "16:9",
})
r.raise_for_status()
task = r.json()

while True:
    time.sleep(task.get("next_poll_after_seconds", 5))
    s = requests.get(f"{BASE}/api/gv2/video/tasks/{task['task_id']}", headers=H).json()
    if s["status"] == "SUCCEEDED":
        print(s["result_url"])   # 立刻转存，地址会失效
        break
    if s["status"] == "FAILED":
        raise RuntimeError(s.get("status_message"))
```

---

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

官方工作台调的就是同一批接口，只是它走浏览器会话而不是密钥：

| 前端动作 | API |
| --- | --- |
| 模型广场 / 模型条 | 内置模型表，见第 5 节 |
| 提交生成 | `POST /api/gv2/video/tasks`、`POST /api/gv/tasks` |
| 生成队列进度 | `GET /api/gv2/video/tasks/{id}`、`GET /api/gv/tasks/{id}` |
| 图片生成 | `POST /api/gi/images/generations` |
| 余额与流水 | `GET /api/wallet` |

第三方用密钥、官方前端用会话令牌，两条路径落到同一个积分账户、同一套计费。

---

## 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. 变更记录

| 版本 | 日期 | 内容 |
| --- | --- | --- |
| v1 | 2026-11-16 | 密钥自助生成（不用审核）、真实可调用接口、视频/图片示例、真实价目 |
| 0.1 | 2026-11-15 | 初稿：认证、模型、视频/图片任务、素材、Webhook、错误码、限流 |

---

## 18. 后续规划

已经上线：密钥自助发放、余额与流水、视频/图片提交与查询、取消、失败自动退款。

还在做：

1. `POST /v1/videos` 这类统一契约（现在用的是站点内部路径）
2. 任务列表、删除、素材上传与预签名
3. Webhook 回调（现在只能轮询）
4. 用量统计页与账单导出
5. 沙箱环境（不出真片、不扣积分）
