# 媒体请求约定

> 平台 API 中图片、视频和 3D 请求的公共规则：公共字段、任务等待、幂等重放与重试。

媒体生成沿用平台统一的[地址与鉴权](access.md)，本页补充媒体请求特有的规则。先查询模型能力，再提交任务，最后读取产物和结算；具体请求体见对应的图片、视频或 3D 生成页。

<a id="media-access-h-3cf89395"></a>

## 地址与身份

当前网关根地址为 `https://platform.sgt.site`；平台媒体请求使用 `/media/v1` 路径前缀，对应 Base URL 为 `https://platform.sgt.site/media/v1`。

模型查询、生成提交、任务查询和取消都使用 `Authorization: Bearer` 加完整虚拟密钥，写法和变量设置见[地址与鉴权](access.md)；示例中的 `GATEWAY_ORIGIN` 不包含 `/media/v1`，命令会显式附加接口路径。生成调用必须归属于企业内的使用人或应用，并具备模型授权与可用预算；平台管理权限本身不授予消费资格。

模型 ID 使用[模型列表](models.md#models-media)查询结果中的完整名称，并与模型授权、价格和账单一致。文档中的示例模型不代表当前密钥已经获准使用。具体接口如下：

| 你要做的事 | 方法与路径 | 下一步文档 |
| --- | --- | --- |
| 查询可用模型与参数 | `GET /media/v1/models` | [模型列表](models.md#models-media-list) |
| 查询单个模型的能力 | `GET /media/v1/models/{model}` | [模型列表](models.md#models-media-list) |
| 生成图片 | `POST /media/v1/images/generations` | [图片生成](media-images.md) |
| 生成视频 | `POST /media/v1/videos/generations` | [视频生成](media-videos.md) |
| 生成 3D | `POST /media/v1/3d/generations` | [3D 生成](media-3d.md) |
| 查询已有任务 | `GET /media/v1/tasks/{id}` | [任务查询与结算](media-tasks.md) |

先确认模型 `type` 与提交路径匹配。当前尚未开放统一音频生成；不要构造未发布的接口地址。

<a id="media-access-h-ffe28b96"></a>

## 请求规则

生成提交使用 HTTP POST 和 JSON 请求体。GET 查询不需要请求体。生成提交的请求头为：

| 请求头 | 必填 | 含义 |
| --- | --- | --- |
| `Authorization` | 是 | `Bearer <完整虚拟密钥>` |
| `Content-Type` | 是 | `application/json` |
| `Idempotency-Key` | 否，建议提供 | 同一业务生成使用固定键，以便断线后安全重放；规则见下文 |

以下是各类生成接口共用的请求字段。具体生成参数如 `prompt`、`n`、`duration`、`resolution`，以当前模型的能力描述和对应生成页为准。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | [模型列表](models.md#models-media-list)返回的完整 ID，必须与提交路径的类型一致 |
| `wait` | integer | 否 | 0–50 秒，默认 0；只控制本次 HTTP 响应等待时间，不改变任务身份或生成方式 |
| `metadata` | object | 否 | 调用方自定义业务信息，随任务原样返回；JSON 编码后不超过 64 KiB，不要放密钥或秘密 |
| `references` | array | 否 | 参考素材数组；按当前模型声明的角色、类型和数量提供，详见[参考文件与素材](media-files.md) |
| `provider_options` | object | 否 | 厂商特有参数，按能力描述放在对应命名空间中，例如 `{"volcengine":{"watermark":false}}` |

通用生成参数放在顶层，厂商选项只放在 `provider_options` 下。每个模型仅接受已声明的字段和值；未知字段、显式 `null`、类型错误、同一语义重复配置或超出范围的值均返回 HTTP 400。省略可选字段和传入 `null` 不等价。整个 JSON 请求不超过 4 MiB，`prompt` 不超过 32,000 字节，具体模型可以有更严格的要求。

<a id="media-access-h-41fe2b3a"></a>

### 等待时间与响应

所有生成结果都用任务对象表达，包括上游同步完成的模型。`wait: 0` 表示尽快返回受理结果；例如设置 `wait: 50` 时，平台可在这次 HTTP 请求内最多等待 50 秒。等待结束不取消生成，后续通过任务 ID 查询。

| 情形 | HTTP 状态 | 响应与后续处理 |
| --- | --- | --- |
| 首次提交，任务仍是 `queued`、`running` 或 `reconciling` | 202 | 返回任务对象，保存 `id`，继续查询 |
| 首次提交，在等待窗口内已进入确认终态 | 200 | 返回任务对象，检查 `status`、`artifacts` 和 `billing` |
| 同键重放已受理请求 | 200 | 返回原任务当前状态，不创建新任务 |
| 查询已有任务 | 200 | 返回任务当前状态，可能仍未完成 |

HTTP 200 不等于生成成功；HTTP 202 也不等于错误。即使 `succeeded`，也要检查非空产物、每项 `state`、非空地址和完整下载；产物缺失或下载失败继续查询同一个任务。任务的生成状态、产物可读状态和账务状态需要分别判断，完整响应示例见[任务查询与结算](media-tasks.md)。

<a id="media-access-h-909a2575"></a>

## 幂等与重试

生成提交可带 `Idempotency-Key`，取 1–255 个可见 ASCII 字符，不包含空格或换行。建议用自己系统的业务生成 ID，例如 `order-20261014-image-001`；同一业务生成的重试沿用原键，新的生成使用新键。

幂等键按消费主体、虚拟密钥和提交路径隔离。原请求已受理成任务后，使用相同虚拟密钥、路径、键与规范化请求内容重放，会返回原任务当前状态，不产生新的上游调用或资金预留；`wait` 可以改变。若原请求在创建任务前失败，平台完成资金释放与受理恢复后，同键重放可以重新受理。没有幂等键时，每次提交都是独立生成，不能依赖请求体相同来去重。

| 情形 | 结果 | 调用方处理 |
| --- | --- | --- |
| 原任务已受理 | HTTP 200，返回原任务当前状态 | 保存并继续查询同一个 ID |
| 同键但请求内容不同 | HTTP 409 `idempotency_conflict` | 核对原请求；新的生成使用新键 |
| 首次请求仍在受理或恢复中 | HTTP 409 `idempotency_in_progress`，附 `Retry-After` | 按提示退避，用同键重放 |
| 模型权限已撤销 | HTTP 403 | 不返回任务内容 |

已受理任务的幂等关系至少保留 24 小时。任务尚在 `queued`、`running` 或 `reconciling` 时保留，进入终态后再保留至少 24 小时；账务仍待处理时继续保留。重启不会丢失已持久化的幂等关系。保留期后重用旧键不能保证去重；受理前失败且已完成恢复的请求不适用这项保留承诺。

遇到网络超时、网关错误或响应丢失时，按以下顺序处理：

1. 已拿到任务 `id`：查询原任务，不重新提交。
2. 没拿到任务 `id`，但提交时有幂等键：使用原虚拟密钥、路径、键和内容重放；收到 `idempotency_in_progress` 时按 `Retry-After` 退避。
3. 既没有任务 ID，也没有幂等键：不要自动再次生成，保存请求标识交由平台核对。

`reconciling` 表示平台仍在确认原提交或结果，应继续查询同一任务；不能据此判断免费或改用新键再次提交。本页的幂等约定只适用于 `/media/v1` 生成接口。

<a id="media-access-h-538e213f"></a>

## 鉴权与调用失败

媒体接口的错误统一使用顶层 `error` 对象和 `request_id`，按 `error.code` 判断原因。错误格式、每个错误码的 HTTP 状态与处理方式、常见报错原文和重试判断，集中在[媒体错误处理](media-errors.md)；接入调试时的速查表见[快速开始：调试与排错](overview.md#overview-section-3)。

预算不足时检查 `error.code: "insufficient_budget"`，不要只靠某一个 HTTP 状态识别。已用尽额度但仍有效、未禁用且有权限的虚拟密钥，可以查询已受理任务。

任务返回的平台签名产物下载地址自带限时签名，读取时不需要虚拟密钥。不要把 `Authorization` 转发给产物的外部域名；具体下载规则见[任务产物](media-tasks.md#media-tasks-h-faa3e87e)。

<a id="media-access-h-76486927"></a>

## 兼容约定

`/media/v1` 内只新增字段、枚举、模型和错误码，不改变已有字段含义。客户端对响应的未知字段和新增枚举应容错；请求侧仍严格校验。生成状态、产物可读状态、账务状态和客户端预览能力分别判断，见[任务与结算](media-tasks.md)。不能把 `kind`、序号或请求格式当作返回文件的格式；未知格式保留原文件，不自动再次生成。