# 图片与视频 API

视频新接入与网页生成统一使用 `/v1/videos`。模型详情、表单与请求校验共用能力定义。
旧 `/api/media/tasks` 保留为兼容入口，与新入口复用任务、幂等和执行流程；图片仍使用它。

## 视频主接口

| 操作 | 接口 |
| --- | --- |
| 查询本人获准模型与规格 | `GET /v1/videos/models` |
| 上传素材（不计费） | `POST /v1/videos/references`，multipart `file` |
| 仅校验，不生成 | `POST /v1/videos/validate` |
| 提交，携带 Idempotency-Key | `POST /v1/videos` |
| 查询、下载 | `GET /v1/videos/{id}`、`GET /v1/videos/{id}/content` |
| 仅重试归档 | `POST /v1/videos/{id}/retry-archive` |

```json
{"model":"seedance-2.5-anmiao-quannengcankao","prompt":"保持参考主体外观，缓慢转动镜头","seconds":4,"resolution":"720p","aspect_ratio":"16:9","references":[{"id":123,"role":"reference_image"}]}
```

将 123 替换为本人上传的素材 ID。`seconds` 为整数；`resolution` 与 `aspect_ratio` 在顶层；
速度版本等模型特有参数放 `metadata`（Seedance 2.0 为 `metadata.version`；Seedance 2.5 满血版为
`metadata.web_search`、`metadata.reference_mode`）。
新请求始终包含 `references`（纯文生为 `[]`），不混用 `metadata.content`。
202 与 `gv_` 开头的 ID 表示已排队，关闭页面后继续；`completed` 后下载。
`uncertain` 不自动重发，`archive_failed` 只恢复归档。跨接口使用同一幂等键与等价请求复用原任务。

网页通过同源会话核验本人绑定的原 API Key，API 客户端使用 Bearer；管理员身份不能替代客户密钥。
后台任务不接受带 IP 白名单的 Key。实际扣款仍由 new-api 负责，上传不计费。

### Seedance 素材范围

- **2.5 全能参考**：4–30 秒，480p / 720p / 1080p；至少一种素材，参考图 ≤30、视频 ≤10、音频 ≤10。
  带视频时整段按含视频档秒价收费。
- **2.5 满血版**（`seedance-2.5-guanfang-anmiao`）：4–30 秒，480p / 720p / 1080p，画幅含 adaptive。
  纯文生、首帧（1 张，此线路不支持尾帧）或参考模式；首帧不混用参考模式。
  参考图 ≤30、视频 ≤10、音频 ≤10，音频可单独使用。
  视频 MP4，每个 2–30 秒、合计 ≤30 秒，像素 409,600–8,295,044、帧率 23.8–60、宽高比 0.4–2.5。
  `web_search`：`off`（默认）或 `on`（联网搜索）。`reference_mode`：带参考视频时可选
  `omni`（全能参考，默认）或 `extend`（延长视频，须至少 1 个参考视频）。首帧与 `extend` 只支持 `adaptive`。
  带参考视频时整段按含视频档秒价收费，不另收参考视频费。
- **2.0 满血版**：4–15 秒；standard 为 720p / 1080p / 4k，fast 与 mini 为 480p / 720p。
  纯文生、首尾帧或参考模式；首尾帧不混用参考模式。参考图 ≤9、视频 ≤3、音频 ≤3，音频须搭配图或视频。
  视频 MP4，每个 2–15 秒、合计 ≤15 秒，像素 409,600–927,408、帧率 23.8–60、宽高比 0.4–2.5。
  带参考视频按含视频成片秒价，另加参考视频秒价 × 计费秒数：每段向下取到 0.1 秒相加，
  不足成片秒数 × 2/3 向上取整到整秒时按后者计。
- 上传支持 PNG/JPEG/WebP、MP4、WAV。图片每张 ≤10 MiB、最短边 ≥300 px；视频每个 ≤50 MB；音频每段 ≤10 MiB。
  图片和音频内联总量 ≤30,000,000 字节。供应商视频取件绑定账户文件和任务、逐次审计、任务结束撤销。
  其它音频格式仍可按既有原生模型合同使用内联或 HTTPS 素材；上传接口不会把未知格式当作可用文件。

### 旧调用兼容

旧 `/v1/videos` 的原生正文（没有 `references`）、`metadata.content`、multipart 与原生任务 ID
继续走现有代理和插件；不自动迁移已提交任务，不改变其计费或查询方式。
新入口有 `references` 的请求进入同一个持久队列，工作进程转换为原生正文后仅发送一次，避免递归入队。
下文保留 `/api/media/tasks` 的图片与旧视频协议参考；视频新程序以上面的接口为准。

所有请求（包括下载）都必须携带 `Authorization: Bearer <同一把API密钥>`。
身份登录、平台管理员令牌不能替代 API 密钥。任务与创建它的 Key 绑定，其他 Key 即便同属一个机构也不能读取此任务。

## 1. 查询获准模型与规格

`GET /api/media/models`

返回 `data[]`：`id`、`type`（image/video）、`parameters`、`reference_roles`、`reference_types`、`reference_constraints`（上传约束）、`notes`、`documentation_url`。
仅列出当前 Key 获准且平台登记过的媒体模型，不暴露供应商价格。

- 图片：每个任务生成一张，`parameters.size.values` 是此接口已开放的显式尺寸。
  列表为空时省略 size，使用供应商默认规格；不要套用其他模型的 1024×1024。
- Seedream 5：默认 2048×2048，首版开放已实测的 2048×2048 与 4096×4096。
- Wan2.7 image pro：默认 1024×1024，可选 2048×2048；4096×4096 尚未按当前报价开放。
- 视频：显式提供整数 `seconds`、`resolution`，可选 `ratio`，默认 16:9。
  通用安全范围为 1–60 秒，**不是每个模型都支持这个范围**；模型特有时长限制仍由上游校验。
  `resolution.values` 非空时仅允许这些档位，空列表表示平台尚未登记枚举，不表示所有分辨率均可用。
- 参考素材接入 PNG/JPEG/WebP 图片；参考视频接 MP4，音频接 WAV；各模型支持角色与数量以能力查询为准。
  Seedance 支持 first_frame/last_frame/reference_image（2.5 满血版只有 first_frame）；Seedream 支持 reference_image。
  Nano Banana Pro（`gemini-3-pro-image`）与 Nano Banana 2（`gemini-3.1-flash-image`）
  支持 `reference_image`，一次最多 8 张；现有及新建的普通销售线路同样支持。
  ToAPIs 的 GPT Image 2 / 2 official、普通 GPT Image 2.5 Flare / Sunburst、Seedream 4.5
  支持最多 8 张 `reference_image`；Vidu Q2 Fast / Pro 最多 7 张。
  具体取值、调用范围与上传边界见[参考图协议](toapis-reference-images.md)。
  MiniMax-H3 支持 first_frame/last_frame/reference_image，具体限制见下方示例。
  kuadd 的 `gk-video-3.5` 必须提供 1 张 `first_frame`；`hailuo-h3-cankaosheng`
  必须提供 1–5 张 `reference_image`，只展示已登记售价的分辨率。
  kuadd Seedance 2.5 全能参考、2.5 满血版与 2.0 均支持本站上传素材；视频统一使用本文开头的 `/v1/videos`。
  其他模型当前只开放无参考图请求，不能静默忽略不支持的参考图。

规格是保守开放范围，不能把定价配置中的“任意尺寸同价”当成“任意尺寸可生成”。

ToAPIs 受控渠道的 `viduq3-pro`、`kling-3.0-turbo`、`wan2.6` 本轮仅支持
5秒、16:9纯文生，不接参考素材、audio 或额外控制。2026-10-29 用户决定暂不接入这三款和
`wan3.0-video` 的带图能力，四款生产目录已标记为下架，未来启用须重新走上架核验。
以下参数仅保留历史合同：Vidu Q3 Pro支持540p/720p/1080p，
其余两款720p/1080p；同时仍须在模型列表登记相应档位。旧 `/v1/videos` 请求使用
`seconds: "5"` 与 `metadata: {"resolution":"720p","ratio":"16:9"}`，
顶层与 metadata 冲突会拒绝。上述限制仅属于该 ToAPIs 渠道，不推断同型号其他供应商能力。
功能成功不代表成本已自动核准：真实终态若未返回独立秒数，逐笔实际成本/售价核验保持未知，
不把请求的5秒当作独立实际交付时长。

## 2. 上传参考图（不生成、不扣积分）

```sh
export ORIGIN="https://gw-test.kuadd.com"
# API_KEY 从安全配置读取，不写入代码或日志。
curl "$ORIGIN/api/media/references" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@reference.png"
```

响应 `201`：`{"id":123,"content_type":"image/png","bytes":12345}`。
只收一个 `file`，单文件不超过 10 MB，按魔数判断类型、最短边至少 300px。
引用时使用返回的整数 ID。文件归属按机构校验，不接收任意外部下载 URL。
网关内部读取图片并按模型协议转换，包括 Seedance 的 `metadata.content` 和首帧/尾帧角色。
Nano Banana 使用图片 `image` 数组内联传递，不向上游提供本站鉴权下载地址。

## 3. 提交统一任务

### 提交前只校验

`POST /api/media/tasks/validate` 接收与创建任务相同的 JSON，使用同一把 API Key，不要求 `Idempotency-Key`。
它检查当前模型授权、参数、参考素材归属以及后台任务的 Key 限制，不创建任务、不占用幂等编号、不调用生成或扣费。

```sh
curl "$ORIGIN/api/media/tasks/validate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan2.7-image-pro","prompt":"一只猫在窗边","parameters":{"size":"1024x1024"}}'
```

成功返回 `200`，字段包括 `valid: true`、`normalized`（规范化请求）、`type`。
当前已接入模型尚未绑定新产品发布版本，`product_version`、`variant_id` 返回 `null`，
`estimate.status` 为 `unknown` 并说明原因，不返回零费用或承诺冻结售价。
失败沿用提交接口的 `error` 和 HTTP 状态；401 表示密钥不可用，400 表示当前准入不满足，
503 表示权限读取或存储不可用。通过只表示此刻的网关准入检查通过，不保证上游接受、余额充足或任务成功；
真正提交与出队仍会重查。此请求不经过 new-api，因此不适用 new-api 的 Key 调用限流。

### 创建任务

`POST /api/media/tasks`，JSON 请求，必须带 `Idempotency-Key`（1–128 字符）。
同一 Key、同一幂等标识、同一请求始终返回原任务；改变参数必须使用新的幂等标识。
**网络超时后不得换幂等标识重试**，否则会被视为另一笔生成。

图片示例：

```sh
curl "$ORIGIN/api/media/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: project-shot-001-image-v1" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan2.7-image-pro","prompt":"一只猫在窗边", "parameters":{"size":"1024x1024"}}'
```

视频请求体示例（模型必须获准，参考图 ID 替换为真实上传结果）：

```json
{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "镜头缓慢推进",
  "parameters": {"seconds": 5, "resolution": "720p", "ratio": "16:9"},
  "references": [{"id": 123, "role": "first_frame"}]
}
```

### Nano Banana 带参考图生成图片

先上传参考图，再将返回的 ID 放进 `references`：

```json
{
  "model": "gemini-3.1-flash-image",
  "prompt": "保留参考图中的人物，将背景改成海边",
  "references": [{"id": 123, "role": "reference_image"}]
}
```

Nano Banana Pro 改用 `gemini-3-pro-image`；使用销售线路时传该线路的完整调用 ID。
每张参考图仍受上述格式、大小、尺寸和账户归属校验；上传本身不计费。
省略 `references` 仍为文生图。生成后沿用下方任务查询与下载接口。

### MiniMax-H3 带参考图生成视频

MiniMax-H3 是视频模型。先上传参考图，然后提交：

```json
{
  "model": "MiniMax-H3",
  "prompt": "保持人物外观一致，镜头缓慢推进",
  "parameters": {"seconds": 4, "resolution": "768p", "ratio": "16:9"},
  "references": [{"id": 123, "role": "reference_image"}]
}
```

- 支持 4–15 整数秒，目前开放 768p；提示词最多 7000 字符。
- 普通参考图使用 `reference_image`，最多 5 张。
- 从指定画面开始或结束时使用 `first_frame` / `last_frame`，各最多一张；不能与 `reference_image` 混用。
- 首尾帧模式按输入图片确定画幅，网关规范为 `adaptive`；纯文生不能使用 `adaptive`。
- 图片最短边至少 300 px、最长边最多 5760 px，宽高比 0.4–2.5；本站上传限 PNG/JPEG/WebP、单张 10 MB。
- 前 5 张无额外输入费用；更多图片以及视频、音频参考尚未接入计费，因此暂不开放。

旧 `/v1/videos` 接口也可以使用图片：提供 `prompt`、字符串 `seconds`，并将图片放进 `metadata.content`，不要使用顶层 `images` 或 `input_reference`：

```json
{
  "model": "MiniMax-H3", "prompt": "镜头缓慢推进", "seconds": "4",
  "metadata": {
    "resolution": "768p", "ratio": "16:9",
    "content": [{"type": "image_url", "image_url": {"url": "https://你的图片地址/reference.png"}, "role": "reference_image"}]
  }
}
```

`image_url.url` 支持公开图片 URL 或 `data:image/png;base64,...` 等图片 data URL；本站鉴权下载地址不能直接作为上游取图 URL。新程序优先使用上传 ID 的统一接口。

协议依据：[MiniMax H3 v2](https://platform.minimax.io/docs/api-reference/video-generation-v2-create)、[输入素材计费](https://platform.minimax.io/docs/guides/pricing-paygo#video)。

返回 `202` 和 `Location` 查询路径：

```json
{"id":"任务ID","model":"wan2.7-image-pro","kind":"image","status":"queued","error":null,"outputs":[],"retry_archive":false,"created_at":0}
```

202 仅表示本站已持久化排队，不表示上游已经受理或生成完成。
后台读取原 Key 并执行，权限变化会重新检查；不会换用机构的其他 Key。
首版不接入带原生 IP 白名单的 Key（后台服务器 IP 不等于调用方 IP），此类 Key 保持走原 `/v1` 接口。

## 4. 查询和下载

`GET /api/media/tasks/{id}`，建议每 5–10 秒查询一次。

| status | 含义与操作 |
|---|---|
| queued | 等待 worker |
| submitting | 正在提交上游；不能自行重新生成 |
| running | 上游处理中，后台自动查询 |
| archiving | 已取得生成结果，正在归档 |
| completed | 本站已有产物，可下载 |
| archive_failed | 原结果存在但归档失败；只重试归档 |
| uncertain | 可能已受理，结果待核验；不要重新生成，向平台提供任务 ID |
| failed | 校验被拒或上游报告失败；扣款/退款看实际账单 |
| paused | 原密钥不可用，需要平台核验原任务；不自动替换 Key |
| expired | 任务内容已按保留期清理 |

`outputs[]` 含 `id` 和站内相对路径 `url`。将路径拼到 ORIGIN，下载时仍使用同一把 API Key：

```sh
curl "$ORIGIN/api/media/tasks/$TASK_ID/outputs/0" \
  -H "Authorization: Bearer $API_KEY" \
  --fail -o output.png
# 视频保存为 output.mp4。不要把 API Key 附加到站外地址或重定向目标。
```

这解决的是统一的下载约定；漏带 Authorization 仍会返回 401。
平台不返回无鉴权直链或 S3 预签名地址。

## 5. 只重试文件归档

`POST /api/media/tasks/{id}/retry-archive`，同一 Key 鉴权，空请求体。
仅 `archive_failed` 状态接受，其他状态返回 409。重试只读取原结果并下载，绝不创建新的生成任务。
后台每个步骤持久化，服务重启后会恢复查询/归档。
提交步骤若失联超过 15 分钟则标为 uncertain，永不自动重新提交。

## 6. Seedance 原生调用兼容

旧正文使用顶层整数 `seconds`、`resolution`、`aspect_ratio`，速度版本放 `metadata.version`，
URL 素材放 `metadata.content`，且不带 `references`。该方式仍可查询原生任务 ID。
Seedance 2.5（全能参考与满血版）支持 HTTPS 视频地址及模型合同允许的图像/音频 data URL；
2.5 满血版的选项同样放 `metadata.web_search` / `metadata.reference_mode`，首帧用 `role=first_frame`；
Seedance 2.0 的视频必须是本站审计签发的取件地址，因此新程序应使用本文开头的上传 ID 请求。
无需让客户自行签发取件凭证，也无需改用另一个视频生成接口。