MG-04-001 公共API

本契约供私有 new-api 供应入口调用；新平台客户、销售价格与结算属于 Core。机器契约为 openapi/openapi.json，共享示例为 openapi/examples.json。历史图像/模型广场接口已移除。

当前接口按实现保留，Core/new-api 全链路尚未联调。实际幂等作用域、任务关联、客户结果授权与取消/费用缺口见平台接入核对，不将当前内部身份视为终端客户。

1. 通用约定

Base URL 是网关 Origin，例如：

https://<gateway-domain>

所有内部调用使用：

Authorization: Bearer <GATEWAY_SERVICE_KEY>

服务密钥通过部署环境配置，与管理密钥不同；不得写入面向客户的浏览器代码、日志、Trace 或错误。生成请求应携带客户端生成的幂等键：

Idempotency-Key: <client-generated-key>

相同 Key 与相同规范化请求返回原结果；相同 Key 与不同请求返回 409 IDEMPOTENCY_CONFLICT。

统一错误信封：

{
  "error": {
    "code": "NO_SUPPLY_AVAILABLE",
    "message": "No healthy supply can satisfy this request.",
    "type": "gateway_error",
    "request_id": "req_..."
  }
}

错误不能暴露 Channel、Supply、Provider Key、Provider Task ID、上游正文、内部 URL、签名 URL 或其他用户信息。

2. 动态模型发现

GET /v1/models

只返回已发布且启用的视频标准名称和显式配置的独立供给别名，不返回上游型号、能力、价格或凭据。例如：

{"object":"list","data":[{"id":"seedance-2.5","object":"model","owned_by":"oceanway"}]}

未知或未发布名称在创建任务、获取 Permit 和素材下载前返回 404 MODEL_NOT_FOUND。独立别名只使用其显式绑定的 Supply，不隐式归入 Seedance 标准模型候选集合。

4. 视频公共能力与素材规则

当前冻结的公开视频模型矩阵：

模型	时长	分辨率	比例
`seedance-2.0`	4–15 秒整数	480p、720p、1080p、4k	16:9、adaptive、21:9、4:3、1:1、3:4、9:16
`seedance-2.0-fast`	4–15 秒整数	480p、720p	同 `seedance-2.0`
`seedance-2.0-mini`	5–15 秒整数	480p、720p	16:9、9:16
`seedance-2.5`	4–30 秒整数	480p、720p、1080p	同 `seedance-2.0`
配置的独立别名	平台硬上限 1–30 秒	480p、720p、1080p、2k、4k	按已发布能力与精确供给校验

seedance-2.0-mini 在时长小于 15 秒时最多接受 4 张图、3 段视频和 1 段音频。 2.0 平台总上限是 9 张图、3 段视频和 3 段音频；2.5/别名的 DTO 硬上限是 30/10/10，实际能力必须取已发布目录与具体 Supply 的交集，不代表任何上游已验证支持该上限；单图不超过 12 MiB，单视频不超过 48 MiB，单音频不超过 16 MiB，全部素材合计不超过 120 MiB，参考视频总时长不超过 15 秒。Public Model 可以发布比平台上限更严格的能力。

素材只接受绝对 HTTPS URL 或网关签发的 upload-ref。外部下载经过 SSRF、DNS 重绑定、类型、大小和超时保护。参考音频不能是唯一素材。普通内容拒绝不降低 Channel 或 Supply 基础设施健康。

5. OpenAI 风格视频

POST /v1/videos
Content-Type: application/json

model、prompt、duration 和 resolution 必填；prompt 最长 5,000 个 Unicode 字符；aspect_ratio 默认 16:9。billing_mode 默认 auto，允许按秒、按条、固定区间和分档的有效采购报价参与选路，按本次请求换算总成本。也可显式选择 per_second 或 per_request 限制候选；显式指定后不会自动换计费方式。历史已存储的空值仍按 per_second 恢复，新请求快照明确保存 auto。缺少可执行成本的供给不参与选路。

参考素材字段：

{
  "reference_image_urls": ["https://assets.example.test/reference.png"],
  "reference_videos": ["https://assets.example.test/reference.mp4"],
  "reference_audios": ["https://assets.example.test/reference.mp3"]
}

参考图字段固定为 reference_image_urls。reference_images、seconds、image_url、 image、input_reference、images 和 reference_image_names 都不是这个接口的公开字段；公开视频请求也没有 fallback_mode。

首尾帧模式使用 first_image_url 与 last_image_url，两者必须成对且不能与任何其他参考素材混用。metadata 只接受以下扁平标量白名单：

{
  "seed": 42,
  "negative_prompt": "blurred text",
  "watermark": false,
  "camera_fixed": false
}

创建成功返回 200 OK 和 Location: /v1/videos/task_...：

{
  "id": "task_...",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780000000,
  "seconds": "5"
}

查询和内容：

GET  /v1/videos/{task_id}
GET  /v1/videos/{task_id}/content
HEAD /v1/videos/{task_id}/content

OpenAI 风格状态是 queued、in_progress、completed、failed。任务完成前访问内容返回 409；完成后内容入口返回 307 到平台内容地址。

6. ByteDance ModelArk 视频

POST /api/v3/contents/generations/tasks
Content-Type: application/json

请求使用正式 content 数组：

{
  "model": "seedance-2.0",
  "content": [
    {"type": "text", "text": "城市夜景延时摄影"},
    {
      "type": "image_url",
      "image_url": {"url": "https://assets.example.test/reference.png"},
      "role": "reference_image"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

条目类型是 text、image_url、video_url 和 audio_url；角色是 reference_image、reference_video、reference_audio、first_frame 和 last_frame。last_frame 必须位于更早的 first_frame 之后；帧模式不能包含参考视频或音频。resolution 默认 720p、duration 默认 5、ratio: auto 规范化为 adaptive；mini 默认比例为 16:9。

可选控制字段是 generate_audio、watermark、safety_identifier、service_tier （default 或 flex）、execution_expires_after（3600–259200 秒）和 priority （0–9）。return_last_frame: true 当前不支持。ModelArk 固定按秒计费。

创建成功返回 200 OK、任务 Location 和：

{"id": "task_..."}

查询：

GET /api/v3/contents/generations/tasks/{task_id}

ModelArk 状态是 queued、running、succeeded、failed、cancelled；成功响应在 content.video_url 返回平台 /v1/content/{output_id} 地址。

/v1/media/generate 与 /v1/media/status 不是公开入口，必须返回 404，不得重新挂载。

7. 统一任务与降级披露

GET /v1/tasks/{task_id}

统一状态是 queued、in_progress、succeeded、failed、cancelled。视频查询返回 media_type、model、request_id、尝试次数、时间、输出与只追加生命周期。视频发生已发布降级时返回：

{
  "id": "task_...",
  "object": "media_task",
  "media_type": "video",
  "status": "succeeded",
  "degraded": true,
  "requested_profile": "933",
  "actual_profile": "900",
  "dropped_inputs": ["reference_videos", "reference_audios"],
  "outputs": [
    {
      "id": "out_...",
      "url": "/v1/content/out_...",
      "media_type": "video",
      "content_type": "video/mp4",
      "byte_size": 123456,
      "status": "available"
    }
  ]
}

普通用户生命周期不返回 Channel、Supply、Provider Task、成本、内部 URL、Prompt 或 Provider 错误正文。请求最多首次提交加一次换 Supply 重试，20 分钟截止后不再开始新重试。

8. 内容交付

GET  /v1/content/{output_id}
HEAD /v1/content/{output_id}

网关先校验当前 Key 是否拥有输出。默认可返回短期 307，也可用 ?mode=proxy 流式代理；代理支持 GET、HEAD 和单段 Range。签名过期后重新访问网关获得新地址。素材与结果始终使用平台对象存储地址，不能向用户透传 Provider URL。

9. 使用记录

GET /v1/usage/records
GET /v1/usage/records/{id}

内部服务身份统一归属视频请求；客户账务与逐客户使用记录由 new-api 维护。本服务不接受客户 Key，不提供 /v1/model-square。

10. HTTP 与稳定错误

场景	HTTP	稳定错误码
视频任务接受	200	—
请求、素材或未知字段错误	400	`INVALID_REQUEST`
服务密钥缺失或错误	401	`UNAUTHORIZED`
模型不存在或无权访问	404	`MODEL_NOT_FOUND`
幂等 Key 冲突	409	`IDEMPOTENCY_CONFLICT`
请求或并发容量不足	429	`CAPACITY_UNAVAILABLE`
没有健康供给	503	`NO_SUPPLY_AVAILABLE`
内部故障	500	`INTERNAL_ERROR`

11. 回调边界

首版必须能力是轮询和用户后台状态。Webhook 属于 P1：仅用于异步任务，使用 HMAC，至少一次投递，用户按 Task ID 幂等，回调不包含 Provider URL 或秘密。

MG-04-001 公共API

On this page