公开文档控制台视频制作登录

API 文档

SeeAPI 客户接入文档

覆盖视频生成、图片生成、图片参考生视频、任务查询、模型列表、余额查询、计费行为、错误码和 Webhook 验签。示例基础地址以平台实际分配为准，API Key 只应保存在服务端。

购买额度 / 充值

基础地址https://api.example.com

认证方式Authorization: Bearer sk_live_...

幂等请求Idempotency-Key: client-generated-key

认证与安全

外部 API 使用 API Key 认证。创建 API Key 时，完整密钥只展示一次；之后控制台只展示 key_prefix，请在服务端安全保存密钥，不要放进前端代码、日志、截图或工单。

所有公开 API 请求都带 Authorization: Bearer sk_live_...。
API Key 无效返回 401 invalid_api_key；被暂停或禁用返回 403 系列错误。
可在控制台为每个 API Key 选择模型范围；该范围只能缩小当前客户分组已有权限，不能开通分组外模型。未选择模型时，Key 保持对当前分组全部模型的访问。
使用受限 Key 请求范围外模型时，会在创建任务和扣费前返回 403 model_not_available；携带该 Key 调用 GET /v1/models 只返回它可访问的模型。
建议每次提交任务都带业务侧唯一 Idempotency-Key，例如订单号或请求流水号。

幂等、计费与恢复规则

同一用户使用同一个 Idempotency-Key 和相同请求体，会返回同一个任务，不会重复扣费。
同一个 Idempotency-Key 搭配不同请求体，会返回 409 idempotency_conflict。
平台在创建任务前预扣预计费用；任务成功后按已预扣金额正式结算。
任务失败或取消后，Worker 会自动退款，任务最终通常表现为 refunded。
余额不足返回 402 insufficient_credits，不会创建任务，并会把当前账户下 active API Key 暂停为 balance_paused。
充值后只恢复 balance_paused 的 API Key，不恢复 user_disabled、admin_disabled 或 risk_blocked。

模型与生成能力

视频任务可以选择模型、时长、画幅、分辨率、生成数量、输入模式、声音和搜索开关；任务响应和任务详情继续返回预估、实扣与退款字段。

视频生成不再区分 STD / Pro 输出档，客户只需要选择模型、时长、画幅和分辨率。
seedance-2.0 支持 480p、720p、1080p、4k；seedance-2.0-fast 与 seedance-2.0-mini 支持 480p、720p。
三个模型均支持 4 到 15 秒、七种画幅以及 1、2、4 个输出。
如需核对当前账户档位，请调用 /v1/credits 或联系平台管理员。

参考素材规则

seedance-2.0 和 seedance-2.0-fast 的图片参考统一使用普通参考素材流程；生成请求字段仍为 reference_image_urls。

不上传参考图时按文生视频生成；普通产品、场景、故事板图片使用 reference_image_urls。
所有图片参考先上传到 /v1/assets/references/upload，字段 kind=image，任务里使用当前账号返回的 asset://ref_...。
旧真人素材库中的素材和 portrait URI 不能直接复用；即使素材属于当前账号，也必须重新上传原始图片。
/v1/assets/portraits/upload、face_reference_url 和 image_reference_url 只适用于 input_schema 明确仍支持真人素材的旧模型，不适用于这两个稳定模型。
Studio 选择这两个稳定模型时会禁用旧真人素材，并引导通过普通参考素材接口重新上传。
视频参考和音频参考使用 /v1/assets/references/upload，生成任务里使用返回的 asset_uri；音频文件仅支持 MP3 和 WAV，且必须同时提供图片或视频参考。
平台生成成功的视频会在任务详情里返回 output.generated_reference_uri；同一账号可把这个值放入下一次 reference_video_urls，用于复用平台已生成的视频参考。
单个请求最多使用 9 张图片、3 段视频、3 段音频，总数不超过 15，同一字段内不得重复 URI。
参考视频最长 15 秒。
平台不会在任务详情或 Webhook 中返回生成服务的临时下载地址。
如果素材缺失、过期或跨账号，平台返回 400 validation_error；如果素材来源与模型不兼容，返回不可重试的 400 asset_provider_incompatible。这些错误发生在计费和入队前。

POST/v1/assets/references/upload

上传普通图片参考

上传产品、场景、故事板等普通图片参考，再把返回的 asset_uri 放入 reference_image_urls。平台会在提交上游前校验归属与有效期。

curl https://api.example.com/v1/assets/references/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "kind=image" \
  -F "file=@./product-reference.png"

# 成功响应示例
{
  "id": "ref_xxx",
  "object": "reference.asset",
  "kind": "image",
  "asset_uri": "asset://ref_xxx",
  "status": "active",
  "mime_type": "image/png",
  "size_bytes": 123456,
  "created_at": "2026-06-26T08:00:00.000Z"
}

POST/v1/assets/references/upload

上传视频/音频参考素材

上传视频或 MP3/WAV 音频参考文件，再把返回的 asset_uri 放入对应字段。视频参考当前支持带可读时长的 MP4/MOV。

curl https://api.example.com/v1/assets/references/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "kind=video" \
  -F "file=@./motion-reference.mp4"

curl https://api.example.com/v1/assets/references/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "kind=audio" \
  -F "file=@./audio-reference.mp3"

# 视频成功响应示例
{
  "id": "ref_video_xxx",
  "object": "reference.asset",
  "kind": "video",
  "asset_uri": "asset://ref_video_xxx",
  "status": "active",
  "mime_type": "video/mp4",
  "size_bytes": 1234567,
  "duration_seconds": 6,
  "created_at": "2026-06-26T08:00:00.000Z"
}

POST/v1/images/generations

图片生成

创建同步图片生成任务。成功响应会返回 base64 图片内容，客户侧可保存为图片文件。

curl https://api.example.com/v1/images/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-order-20260703-0001" \
  -d '{
  "model": "image-2-lite",
  "prompt": "一张干净的产品主图，白色背景，柔和自然光。",
  "size": "1024x1024",
  "n": 1,
  "response_format": "b64_json"
}'

POST/v1/images/generations

图片参考改图

提交 1 到 4 张图片参考和提示词，生成保持参考图主体、构图或风格的新图片。参考图建议使用公网 HTTPS 图片 URL。

curl https://api.example.com/v1/images/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-order-20260703-0002" \
  -d '{
  "model": "image-2-pro",
  "prompt": "综合参考图主体和风格，调整为高端商业摄影质感。",
  "size": "2160x3840",
  "input_references": [
    "https://client.example.com/reference-1.png",
    "https://client.example.com/reference-2.jpg"
  ],
  "n": 1,
  "response_format": "b64_json"
}'

POST/v1/images/generations

Nano Banana 图片生成

Nano Banana 使用 image_size 和 aspect_ratio 选择输出规格。当前支持 Flash 和 Pro 两档。

curl https://api.example.com/v1/images/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nano-banana-order-20260708-0001" \
  -d '{
  "model": "nano-banana-flash",
  "prompt": "一张高质感产品海报，柔和灯光，干净背景。",
  "image_size": "2K",
  "aspect_ratio": "9:16",
  "n": 1,
  "response_format": "b64_json"
}'

POST/v1/images/generations

Nano Banana 图片参考编辑

提交 1 到 4 张图片参考，平台会转为上游支持的图片内容格式。

curl https://api.example.com/v1/images/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nano-banana-order-20260708-0002" \
  -d '{
  "model": "nano-banana-pro",
  "prompt": "保持参考图产品外观一致，生成高端电商详情页场景图。",
  "image_size": "4K",
  "aspect_ratio": "3:4",
  "input_references": [
    "https://client.example.com/product-reference.png"
  ],
  "n": 1,
  "response_format": "b64_json"
}'

POST/v1/video/generations

提交视频任务

创建异步视频生成任务。成功时返回 202 Accepted 和任务 ID。

curl https://api.example.com/v1/video/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260510-0001" \
  -d '{
  "model": "seedance-2.0",
  "prompt": "基于产品参考图生成一段自然柔光下的展示视频。",
  "reference_image_urls": [
    "asset://ref_image_xxx"
  ],
  "reference_video_urls": [
    "asset://ref_video_xxx"
  ],
  "reference_audio_urls": [
    "asset://ref_audio_mp3_xxx"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "count": 1,
  "mode": "mixed2video",
  "generate_audio": true,
  "search_enabled": true,
  "callback_url": "https://client.example.com/webhooks/seeapi"
}'

POST/v1/video/generations

复用已生成视频作为参考

任务 succeeded 后，从 /v1/tasks/{task_id} 的 output.generated_reference_uri 取值，放入下一次 reference_video_urls。同一账号、成功任务且可复用的视频才会通过校验。

curl https://api.example.com/v1/video/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260510-0002" \
  -d '{
  "model": "seedance-2.0",
  "prompt": "延续上一条视频的动作节奏，生成同风格的新镜头。",
  "reference_video_urls": [
    "asset://generated-video/job_xxx"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "720p"
}'

POST/v1/videos

图片参考生视频

创建图片参考生视频任务。当前要求单张图片参考加提示词，不支持纯文字生视频。

curl https://api.example.com/v1/videos \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-order-20260703-0001" \
  -d '{
  "model": "grok-imagine-video",
  "prompt": "让参考图中的画面产生轻微电影感推进，保持自然、简洁。",
  "input_reference": "https://client.example.com/reference.png",
  "seconds": 4,
  "size": "1280x720"
}'

POST/v1/chat/completions

流式对话

为已开通 GPT 文本模型的账户创建对话响应，支持文字和图片输入。传 stream: true 时会返回 text/event-stream；视频、音频和通用文件会本地拒绝且不扣费。

curl -N https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-order-20260704-0001" \
  -d '{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "user",
      "content": "请把这段产品介绍改写成更适合短视频口播的版本。"
    }
  ],
  "max_completion_tokens": 800,
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}'

图片尺寸

下表由 Image2 Contract Hub 生成，与 Registry seed、管理员配置校验和 /v1/models 使用同一份尺寸定义。线上实际可用值仍以当前账号从 /v1/models 取得的激活结果为准。

model	1K 方图	1K 横屏	1K 竖屏	2K 方图	2K 横屏	2K 竖屏	4K 横屏	4K 竖屏
`image-2-lite`	1024x1024	1536x864、1360x1024、1536x1024	864x1536、1024x1360、1024x1536	2048x2048	3072x1728、2720x2048、3072x2048	1728x3072、2048x2720、2048x3072	-	-
`image-2-pro`	1024x1024	1536x864、1360x1024、1536x1024	864x1536、1024x1360、1024x1536	2048x2048	3072x1728、2720x2048、3072x2048	1728x3072、2048x2720、2048x3072	3840x2160、3328x2496、3520x2336	2160x3840、2496x3328、2336x3520

Nano Banana 使用 image_size 和 aspect_ratio，不使用 Image2 的 size 字段。nano-banana-flash 和 nano-banana-pro 当前支持同一组规格。

image_size	1:1	16:9	9:16	4:3	3:4	3:2	2:3
`1K`	1024x1024	1536x864	864x1536	1360x1024	1024x1360	1536x1024	1024x1536
`2K`	2048x2048	3072x1728	1728x3072	2720x2048	2048x2720	3072x2048	2048x3072
`4K`	2880x2880	3840x2160	2160x3840	3328x2496	2496x3328	3520x2336	2336x3520

图片参考素材

项目	边界
格式	PNG、JPEG/JPG、WebP。
数量	Image2 和 Nano Banana 支持 1 到 4 张；Grok 只支持 1 张。
Image2 HTTPS URL	推荐方式。URL 必须公网可访问，不能是内网地址、需要登录的地址、带账号密码的地址或过期签名地址；所有参考图合计不超过 20 MiB。平台按当前适配链路处理，客户请求格式保持稳定。
其他图片模型 HTTPS URL	URL 必须公网可访问；具体数量与体积限制以对应模型契约为准。
Grok HTTPS URL	URL 会随请求提交给图片参考生视频服务。请使用非敏感、可公开访问的 HTTPS 图片 URL，不要使用私有地址、登录态 URL 或带敏感签名参数的 URL。
Base64 data URL	仅建议用于 700 KB 以内的小图，格式为 data:image/png;base64,...、data:image/jpeg;base64,... 或 data:image/webp;base64,...。较大图片请压缩或改用 HTTPS URL，否则可能返回 413。

视频任务字段

字段	要求	说明
`model`	必填	当前视频生成模型为 seedance-2.0、seedance-2.0-fast 与 seedance-2.0-mini。
`prompt`	必填	视频提示词，1 到 4000 字符。
`reference_image_urls`	可选	图片参考数组，支持 1 到 9 张。seedance-2.0 和 seedance-2.0-fast 使用当前账号有效的普通参考素材 asset_uri；平台校验后使用其 HTTPS 图片。旧真人素材库及 portrait URI 不能直接复用。纯文生视频可不传。
`reference_video_urls`	可选	视频参考数组，支持 1 到 3 个。使用当前账号有效的参考素材 asset_uri，或同账号成功任务的 output.generated_reference_uri；平台校验后使用其 HTTPS 视频。
`reference_audio_urls`	可选	音频参考数组，支持 1 到 3 个，仅接受 MP3 或 WAV。使用当前账号有效的参考素材 asset_uri，且必须同时提供至少一项图片或视频参考。
`duration`	必填	整数，当前支持 4 到 15 秒。
`aspect_ratio`	必填	支持 adaptive、16:9、4:3、1:1、3:4、9:16、21:9。
`resolution`	必填	seedance-2.0 支持 480p、720p、1080p、4k；seedance-2.0-fast 与 seedance-2.0-mini 支持 480p、720p。
`count`	可选	支持 1、2、4，默认 1。
`mode`	可选	支持 text2video、singleImage2video、frames2video、image2video、mixed2video；省略时自动推断。纯音频请求不支持。
`generate_audio`	可选	是否生成声音，默认 true。
`search_enabled`	可选	是否启用搜索增强，默认 true。
`callback_url`	可选	接收任务 Webhook 通知的地址。当前 MVP 稳定投递成功事件；生产环境请使用 HTTPS。

图片任务字段

字段	要求	说明
`model`	必填	使用 image-2-lite 或 image-2-pro；实际可见模型以 GET /v1/models 为准。
`prompt`	必填	图片提示词，1 到 4000 字符。
`size`	必填	使用当前模型契约列出的精确尺寸。
`input_reference`	图生图可选	旧版单图字段；不要和 input_references 同时传。
`input_references`	图生图可选	1 到 4 张；数组内只能全部为 HTTPS URL 或全部为 Base64 data URL。
`n`	可选	当前固定为 1。
`response_format`	可选	b64_json（默认）或 url。url 返回 seeAPI 托管的短期签名地址，不暴露供应商原始地址。
`output_format`	可选	jpeg 或 png；默认 jpeg。
`quality`	可选	当前固定为 auto。
`moderation`	可选	当前固定为 auto。
`image_size`	Nano Banana 必填	Nano Banana 尺寸档位，当前支持 1K、2K、4K。
`aspect_ratio`	Nano Banana 必填	Nano Banana 画幅比例，当前支持 1:1、16:9、9:16、4:3、3:4、3:2、2:3。

图片参考生视频字段

字段	要求	说明
`model`	必填	当前为 grok-imagine-video。
`prompt`	必填	视频提示词，1 到 4000 字符。
`input_reference`	必填	单张图片参考。推荐使用非敏感、可公开访问的 HTTPS 图片 URL；URL 会随请求提交给图片参考生视频服务。Base64 data URL 只建议用于 700 KB 以内的小图。
`seconds`	必填	整数，当前支持 4 到 15 秒。
`size`	必填	当前支持 1280x720 和 720x1280。
`callback_url`	可选	接收任务 Webhook 通知的地址；生产环境请使用 HTTPS。

流式对话字段

字段	要求	说明
`model`	必填	受邀账户当前可用 gpt-5.5；以 /v1/models 返回为准。
`messages`	必填	对话消息数组，支持 system、developer、user、assistant 角色；用户内容支持文字和图片。
`max_completion_tokens`	必填	本次回复最大输出 token 数；也可使用兼容字段 max_tokens。
`temperature`	可选	0 到 2 的采样温度。
`stream`	推荐	传 true 时返回 text/event-stream，客户侧可边接收边展示。
`stream_options`	可选	建议传 { include_usage: true }，便于平台按上游最终 usage 做结算。
`不支持`	固定	GPT 对话不支持视频、音频或通用文件输入；此类请求会在本地 400 拒绝且不扣费。

GET/v1/tasks/{task_id}

查询任务

轮询任务状态，直到进入 succeeded、refunded、failed 或 canceled。

curl https://api.example.com/v1/tasks/job_xxx \
  -H "Authorization: Bearer sk_live_xxx"

# 成功响应示例
{
  "id": "job_xxx",
  "object": "task",
  "status": "succeeded",
  "model": "seedance-2.0",
  "output": {
    "video_url": "https://cdn.example.com/users/usr_xxx/jobs/job_xxx/output/video.mp4",
    "generated_reference_uri": "asset://generated-video/job_xxx",
    "assets": [
      {
        "type": "output_video",
        "url": "https://cdn.example.com/users/usr_xxx/jobs/job_xxx/output/video.mp4",
        "mime_type": "video/mp4",
        "size_bytes": "12345678",
        "checksum": "sha256:..."
      }
    ]
  },
  "error": null,
  "cost": {
    "estimated_units": 1234567,
    "charged_units": 1234567,
    "refunded_units": 0,
    "currency": "credits"
  },
  "created_at": "2026-05-10T08:00:00.000Z",
  "finished_at": "2026-05-10T08:01:00.000Z"
}

任务状态

状态	含义
`created`	任务已持久化，等待入队；提交响应中会按 queued 展示。
`queued`	已进入队列，等待 Worker 处理。
`running`	正在生成或等待结果回传。
`succeeded`	任务成功，余额正式结算，output 中返回平台存储后的结果地址。
`failed`	任务失败的中间状态；Worker 会继续执行退款流程。
`refunded`	任务失败或取消后已退款，cost.refunded_units 展示退款数量。
`canceled`	任务已取消；如果已预扣，后续会进入退款流程。

GET/v1/models

模型列表

返回当前账户可调用的模型和输入能力 schema；示例为响应节选。

curl https://api.example.com/v1/models \
  -H "Authorization: Bearer sk_live_xxx"

# 响应示例
{
  "object": "list",
  "data": [
    {
      "id": "seedance-2.0",
      "object": "model",
      "code": "seedance-2.0",
      "owned_by": "seeapi",
      "modality": "video",
      "execution_mode": "async",
      "input_schema": {
        "required": ["model", "prompt", "duration", "aspect_ratio", "resolution"],
        "properties": {
          "duration": { "enum": [4, 5, 6, "...", 15] },
          "resolution": { "enum": ["480p", "720p", "1080p", "4k"] },
          "aspect_ratio": { "enum": ["adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9"] },
          "count": { "enum": [1, 2, 4], "default": 1 },
          "mode": { "enum": ["text2video", "singleImage2video", "frames2video", "image2video", "mixed2video"] },
          "generate_audio": { "type": "boolean", "default": true },
          "search_enabled": { "type": "boolean", "default": true },
          "reference_image_urls": { "type": "array", "maxItems": 9 },
          "reference_video_urls": { "type": "array", "maxItems": 3 },
          "reference_audio_urls": { "type": "array", "maxItems": 3, "description": "MP3 or WAV; requires an image or video reference" }
        }
      },
      "pricing_rule": { "currency": "credits" }
    },
    {
      "id": "seedance-2.0-fast",
      "object": "model",
      "code": "seedance-2.0-fast",
      "owned_by": "seeapi",
      "modality": "video",
      "execution_mode": "async",
      "input_schema": {
        "required": ["model", "prompt", "duration", "aspect_ratio", "resolution"],
        "properties": {
          "duration": { "enum": [4, 5, 6, "...", 15] },
          "resolution": { "enum": ["480p", "720p"] },
          "count": { "enum": [1, 2, 4], "default": 1 },
          "generate_audio": { "type": "boolean", "default": true },
          "search_enabled": { "type": "boolean", "default": true }
        }
      },
      "pricing_rule": { "currency": "credits" }
    },
    {
      "id": "image-2-lite",
      "object": "model",
      "code": "image-2-lite",
      "owned_by": "seeapi",
      "modality": "image",
      "execution_mode": "sync",
      "input_schema": {
      "oneOf": [
            {
                  "type": "object",
                  "required": [
                        "model",
                        "prompt",
                        "size"
                  ],
                  "properties": {
                        "model": {
                              "const": "image-2-lite"
                        },
                        "prompt": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 4000
                        },
                        "n": {
                              "type": "integer",
                              "enum": [
                                    1
                              ],
                              "default": 1
                        },
                        "response_format": {
                              "type": "string",
                              "enum": [
                                    "b64_json",
                                    "url"
                              ],
                              "default": "b64_json"
                        },
                        "output_format": {
                              "type": "string",
                              "enum": [
                                    "jpeg",
                                    "png"
                              ],
                              "default": "jpeg"
                        },
                        "quality": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "moderation": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "size": {
                              "type": "string",
                              "enum": [
                                    "1024x1024",
                                    "1536x864",
                                    "1360x1024",
                                    "1536x1024",
                                    "864x1536",
                                    "1024x1360",
                                    "1024x1536",
                                    "2048x2048",
                                    "3072x1728",
                                    "2720x2048",
                                    "3072x2048",
                                    "1728x3072",
                                    "2048x2720",
                                    "2048x3072"
                              ]
                        }
                  },
                  "additionalProperties": false
            },
            {
                  "type": "object",
                  "required": [
                        "model",
                        "prompt",
                        "size",
                        "input_reference"
                  ],
                  "properties": {
                        "model": {
                              "const": "image-2-lite"
                        },
                        "prompt": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 4000
                        },
                        "n": {
                              "type": "integer",
                              "enum": [
                                    1
                              ],
                              "default": 1
                        },
                        "response_format": {
                              "type": "string",
                              "enum": [
                                    "b64_json",
                                    "url"
                              ],
                              "default": "b64_json"
                        },
                        "output_format": {
                              "type": "string",
                              "enum": [
                                    "jpeg",
                                    "png"
                              ],
                              "default": "jpeg"
                        },
                        "quality": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "moderation": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "size": {
                              "type": "string",
                              "enum": [
                                    "1024x1024",
                                    "1536x864",
                                    "1360x1024",
                                    "1536x1024",
                                    "864x1536",
                                    "1024x1360",
                                    "1024x1536",
                                    "2048x2048",
                                    "3072x1728",
                                    "2720x2048",
                                    "3072x2048",
                                    "1728x3072",
                                    "2048x2720",
                                    "2048x3072"
                              ]
                        },
                        "input_reference": {
                              "anyOf": [
                                    {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 29360128,
                                          "pattern": "^data:image\\/(png|jpeg|jpg|webp);base64,[A-Za-z0-9+/]+={0,2}$"
                                    },
                                    {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 4096,
                                          "format": "uri",
                                          "pattern": "^https:\\/\\/.+"
                                    }
                              ]
                        }
                  },
                  "additionalProperties": false
            },
            {
                  "type": "object",
                  "required": [
                        "model",
                        "prompt",
                        "size",
                        "input_references"
                  ],
                  "properties": {
                        "model": {
                              "const": "image-2-lite"
                        },
                        "prompt": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 4000
                        },
                        "n": {
                              "type": "integer",
                              "enum": [
                                    1
                              ],
                              "default": 1
                        },
                        "response_format": {
                              "type": "string",
                              "enum": [
                                    "b64_json",
                                    "url"
                              ],
                              "default": "b64_json"
                        },
                        "output_format": {
                              "type": "string",
                              "enum": [
                                    "jpeg",
                                    "png"
                              ],
                              "default": "jpeg"
                        },
                        "quality": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "moderation": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "size": {
                              "type": "string",
                              "enum": [
                                    "1024x1024",
                                    "1536x864",
                                    "1360x1024",
                                    "1536x1024",
                                    "864x1536",
                                    "1024x1360",
                                    "1024x1536",
                                    "2048x2048",
                                    "3072x1728",
                                    "2720x2048",
                                    "3072x2048",
                                    "1728x3072",
                                    "2048x2720",
                                    "2048x3072"
                              ]
                        },
                        "input_references": {
                              "oneOf": [
                                    {
                                          "type": "array",
                                          "minItems": 1,
                                          "maxItems": 4,
                                          "items": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 29360128,
                                                "pattern": "^data:image\\/(png|jpeg|jpg|webp);base64,[A-Za-z0-9+/]+={0,2}$"
                                          }
                                    },
                                    {
                                          "type": "array",
                                          "minItems": 1,
                                          "maxItems": 4,
                                          "items": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 4096,
                                                "format": "uri",
                                                "pattern": "^https:\\/\\/.+"
                                          }
                                    }
                              ]
                        }
                  },
                  "additionalProperties": false
            }
      ]
},
      "pricing_rule": { "currency": "credits" }
    },
    {
      "id": "image-2-pro",
      "object": "model",
      "code": "image-2-pro",
      "owned_by": "seeapi",
      "modality": "image",
      "execution_mode": "sync",
      "input_schema": {
      "oneOf": [
            {
                  "type": "object",
                  "required": [
                        "model",
                        "prompt",
                        "size"
                  ],
                  "properties": {
                        "model": {
                              "const": "image-2-pro"
                        },
                        "prompt": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 4000
                        },
                        "n": {
                              "type": "integer",
                              "enum": [
                                    1
                              ],
                              "default": 1
                        },
                        "response_format": {
                              "type": "string",
                              "enum": [
                                    "b64_json",
                                    "url"
                              ],
                              "default": "b64_json"
                        },
                        "output_format": {
                              "type": "string",
                              "enum": [
                                    "jpeg",
                                    "png"
                              ],
                              "default": "jpeg"
                        },
                        "quality": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "moderation": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "size": {
                              "type": "string",
                              "enum": [
                                    "1024x1024",
                                    "1536x864",
                                    "1360x1024",
                                    "1536x1024",
                                    "864x1536",
                                    "1024x1360",
                                    "1024x1536",
                                    "2048x2048",
                                    "3072x1728",
                                    "2720x2048",
                                    "3072x2048",
                                    "1728x3072",
                                    "2048x2720",
                                    "2048x3072",
                                    "3840x2160",
                                    "3328x2496",
                                    "3520x2336",
                                    "2160x3840",
                                    "2496x3328",
                                    "2336x3520"
                              ]
                        }
                  },
                  "additionalProperties": false
            },
            {
                  "type": "object",
                  "required": [
                        "model",
                        "prompt",
                        "size",
                        "input_reference"
                  ],
                  "properties": {
                        "model": {
                              "const": "image-2-pro"
                        },
                        "prompt": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 4000
                        },
                        "n": {
                              "type": "integer",
                              "enum": [
                                    1
                              ],
                              "default": 1
                        },
                        "response_format": {
                              "type": "string",
                              "enum": [
                                    "b64_json",
                                    "url"
                              ],
                              "default": "b64_json"
                        },
                        "output_format": {
                              "type": "string",
                              "enum": [
                                    "jpeg",
                                    "png"
                              ],
                              "default": "jpeg"
                        },
                        "quality": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "moderation": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "size": {
                              "type": "string",
                              "enum": [
                                    "1024x1024",
                                    "1536x864",
                                    "1360x1024",
                                    "1536x1024",
                                    "864x1536",
                                    "1024x1360",
                                    "1024x1536",
                                    "2048x2048",
                                    "3072x1728",
                                    "2720x2048",
                                    "3072x2048",
                                    "1728x3072",
                                    "2048x2720",
                                    "2048x3072",
                                    "3840x2160",
                                    "3328x2496",
                                    "3520x2336",
                                    "2160x3840",
                                    "2496x3328",
                                    "2336x3520"
                              ]
                        },
                        "input_reference": {
                              "anyOf": [
                                    {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 29360128,
                                          "pattern": "^data:image\\/(png|jpeg|jpg|webp);base64,[A-Za-z0-9+/]+={0,2}$"
                                    },
                                    {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 4096,
                                          "format": "uri",
                                          "pattern": "^https:\\/\\/.+"
                                    }
                              ]
                        }
                  },
                  "additionalProperties": false
            },
            {
                  "type": "object",
                  "required": [
                        "model",
                        "prompt",
                        "size",
                        "input_references"
                  ],
                  "properties": {
                        "model": {
                              "const": "image-2-pro"
                        },
                        "prompt": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 4000
                        },
                        "n": {
                              "type": "integer",
                              "enum": [
                                    1
                              ],
                              "default": 1
                        },
                        "response_format": {
                              "type": "string",
                              "enum": [
                                    "b64_json",
                                    "url"
                              ],
                              "default": "b64_json"
                        },
                        "output_format": {
                              "type": "string",
                              "enum": [
                                    "jpeg",
                                    "png"
                              ],
                              "default": "jpeg"
                        },
                        "quality": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "moderation": {
                              "type": "string",
                              "enum": [
                                    "auto"
                              ],
                              "default": "auto"
                        },
                        "size": {
                              "type": "string",
                              "enum": [
                                    "1024x1024",
                                    "1536x864",
                                    "1360x1024",
                                    "1536x1024",
                                    "864x1536",
                                    "1024x1360",
                                    "1024x1536",
                                    "2048x2048",
                                    "3072x1728",
                                    "2720x2048",
                                    "3072x2048",
                                    "1728x3072",
                                    "2048x2720",
                                    "2048x3072",
                                    "3840x2160",
                                    "3328x2496",
                                    "3520x2336",
                                    "2160x3840",
                                    "2496x3328",
                                    "2336x3520"
                              ]
                        },
                        "input_references": {
                              "oneOf": [
                                    {
                                          "type": "array",
                                          "minItems": 1,
                                          "maxItems": 4,
                                          "items": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 29360128,
                                                "pattern": "^data:image\\/(png|jpeg|jpg|webp);base64,[A-Za-z0-9+/]+={0,2}$"
                                          }
                                    },
                                    {
                                          "type": "array",
                                          "minItems": 1,
                                          "maxItems": 4,
                                          "items": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 4096,
                                                "format": "uri",
                                                "pattern": "^https:\\/\\/.+"
                                          }
                                    }
                              ]
                        }
                  },
                  "additionalProperties": false
            }
      ]
},
      "pricing_rule": { "currency": "credits" }
    },
    {
      "id": "grok-imagine-video",
      "object": "model",
      "code": "grok-imagine-video",
      "owned_by": "seeapi",
      "modality": "video",
      "execution_mode": "async",
      "input_schema": {
        "required": ["model", "prompt", "input_reference", "seconds", "size"],
        "properties": {
          "input_reference": { "description": "single base64 image data URL or HTTPS image URL" },
          "seconds": { "enum": [4, 5, 6, "...", 15] },
          "size": { "enum": ["1280x720", "720x1280"] }
        }
      },
      "pricing_rule": { "currency": "credits" }
    },
    {
      "id": "gpt-5.5",
      "object": "model",
      "code": "gpt-5.5",
      "owned_by": "seeapi",
      "modality": "text",
      "execution_mode": "sync",
      "input_modalities": ["text", "image"],
      "input_schema": {
        "required": ["model", "messages"],
        "properties": {
          "messages": { "type": "array", "description": "text and image content parts only" },
          "max_completion_tokens": { "type": "integer" },
          "stream": { "type": "boolean" }
        }
      },
      "pricing_rule": { "currency": "credits" }
    }
  ]
}

GET/v1/credits

查询余额

返回账户余额、币种和因余额不足暂停的 API Key 数量。

curl https://api.example.com/v1/credits \
  -H "Authorization: Bearer sk_live_xxx"

# 响应示例
{
  "balance_units": 12000000,
  "currency": "credits",
  "price_tier": "retail",
  "paused_api_keys": 0
}

Webhook 事件与签名

提交任务时传入 callback_url 后，可用 Webhook 接收任务通知。当前 MVP 稳定投递 task.succeeded；核心事件格式已覆盖 task.refunded、task.failed和 task.canceled，这些非成功终态会在后续版本升级为稳定投递承诺。请始终以 /v1/tasks/{task_id} 作为最终状态兜底；Webhook 投递失败不会改变任务最终状态，也不会再次触发扣费或退款。

Header：x-webhook-id、x-webhook-timestamp、x-webhook-signature。
签名算法：HMAC_SHA256(secret, "{timestamp}.{rawBody}")，Header 值格式为 v1=hex_hmac_sha256。
验签时必须使用收到的原始请求体 raw body，不要使用重新序列化后的 JSON。

POSTclient callback_url

Webhook Payload

succeeded 事件会包含 output；refunded、failed、canceled 的事件格式中 output 为 null，并包含 error。当前 MVP 请不要依赖非成功终态一定投递。

{
  "id": "evt_xxx",
  "type": "task.succeeded",
  "created_at": "2026-05-10T08:01:00.000Z",
  "data": {
    "id": "job_xxx",
    "status": "succeeded",
    "model": "seedance-2.0",
    "output": {
      "video_url": "https://cdn.example.com/users/usr_xxx/jobs/job_xxx/output/video.mp4"
    },
    "error": null
  }
}

NODEx-webhook-signature

Node.js Webhook 验签

示例使用 Node.js 内置 http 和 crypto。请将 SEEAPI_WEBHOOK_SECRET 配置为平台为你的回调地址分配的密钥。

import { createHmac, timingSafeEqual } from "node:crypto";
import http from "node:http";

const WEBHOOK_SECRET = process.env.SEEAPI_WEBHOOK_SECRET;

function verifySignature(rawBody, timestamp, signature) {
  if (!WEBHOOK_SECRET || !timestamp || !signature?.startsWith("v1=")) return false;

  const expected = "v1=" + createHmac("sha256", WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const receivedBuffer = Buffer.from(signature);
  const expectedBuffer = Buffer.from(expected);
  return receivedBuffer.length === expectedBuffer.length
    && timingSafeEqual(receivedBuffer, expectedBuffer);
}

http.createServer((req, res) => {
  if (req.method !== "POST") {
    res.writeHead(405).end();
    return;
  }

  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks).toString("utf8");
    const timestamp = req.headers["x-webhook-timestamp"];
    const signature = req.headers["x-webhook-signature"];

    if (!verifySignature(rawBody, String(timestamp ?? ""), String(signature ?? ""))) {
      res.writeHead(401).end("invalid signature");
      return;
    }

    const event = JSON.parse(rawBody);
    console.log(req.headers["x-webhook-id"], event.type, event.data.id);
    res.writeHead(204).end();
  });
}).listen(3000);

统一错误格式

所有平台错误都使用统一结构；message 可用于排查，业务判断请优先依赖稳定的 code。

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits.",
    "type": "billing_error",
    "request_id": "req_xxx"
  }
}

错误码	类型	HTTP	说明
`invalid_api_key`	`authentication_error`	401	API Key 缺失、格式错误或不存在。
`api_key_disabled`	`authorization_error`	403	API Key 被用户、管理员或风控禁用。
`api_key_paused_insufficient_balance`	`authorization_error`	403	API Key 因余额不足暂停；充值后会自动恢复该类 Key。
`validation_error`	`invalid_request_error`	400	请求字段不符合 input_schema，或 ReferenceAsset 缺失、已过期、不属于当前账号。修正或重新上传素材后使用新的 Idempotency-Key。
`asset_provider_incompatible`	`invalid_request_error`	400	当前模型不能使用该素材来源，且不应重试。请通过普通参考素材接口重新上传原始图片，再使用新的 asset://ref_...。
`unsupported_input_modality`	`invalid_request_error`	400	GPT 对话只支持文字和图片输入；不要传视频、音频或通用文件。
`insufficient_credits`	`billing_error`	402	余额不足，平台不会创建任务，并会暂停当前账户下 active API Key。
`idempotency_conflict`	`invalid_request_error`	409	同一 Idempotency-Key 已用于不同请求体。
`idempotent_stream_replay_unavailable`	`task_error`	409	同一流式请求不能回放原始字节流；请使用新的 Idempotency-Key 重新生成。
`model_not_found`	`model_error`	404	模型不存在。
`model_disabled`	`model_error`	403	模型已禁用。
`provider_not_configured`	`model_error`	500	模型服务未配置。
`task_not_found`	`task_error`	404	任务不存在，或当前 API Key 不属于该任务用户。
`task_timeout`	`task_error`	503	任务处理超时；如已扣费，平台会走退款流程。
`provider_auth_failed`	`provider_error`	502	服务配置异常，请联系平台处理，不要重复提交大量请求。
`provider_invalid_request`	`provider_error`	422	生成服务认为请求无效。
`real_person_reference_requires_asset`	`provider_error`	422	仅适用于 input_schema 明确支持旧真人素材流程的旧模型；不要将真人素材接口用于 seedance-2.0 或 seedance-2.0-fast。
`provider_task_failed`	`provider_error`	502	生成任务失败；请查询任务状态确认是否已退款。
`asset_library_not_configured`	`provider_error`	500	真人素材上传服务未配置，请联系平台处理。
`asset_upload_failed`	`provider_error`	502	真人素材上传失败；文件直传模式请稍后重试。
`storage_file_too_large`	`invalid_request_error`	413	真人素材图片过大，请压缩后重新上传。
`asset_activation_timeout`	`provider_error`	504	真人素材已上传但未及时完成校验，请稍后重试或联系平台。
`provider_unavailable`	`provider_error`	502	生成服务确实暂不可用；该错误不表示素材缺失、过期、跨账号或来源不兼容。
`provider_rate_limited`	`provider_error`	429	生成服务限流。
`provider_timeout`	`provider_error`	503	生成服务超时。
`storage_upload_failed`	`storage_error`	502	结果文件写入平台存储失败；请查询任务状态确认是否已退款。
`internal_error`	`internal_error`	500	平台内部错误。

常见处理建议

情况	建议动作
`401 / 403`	先检查 API Key 是否复制完整、是否放在服务端、账户余额是否已耗尽。
`402 insufficient_credits`	停止重试，联系平台充值；充值后 balance_paused 的 Key 会恢复。
`409 idempotency_conflict`	换一个新的 Idempotency-Key，或使用原请求体查询旧任务。
`400 asset_provider_incompatible`	不要重试原请求。重新上传原始图片，并把新的 asset://ref_... 放入 reference_image_urls。
`400 validation_error（素材）`	确认 ReferenceAsset 存在、未过期且属于当前账号；修正后使用新的 Idempotency-Key。
`422 real_person_reference_requires_asset`	仅对明确支持旧真人素材流程的旧模型使用 /v1/assets/portraits/upload；seedance-2.0 和 seedance-2.0-fast 改走普通参考素材上传。
`429 / 503`	按指数退避重试任务查询；提交接口不要高频重复打。
`refunded`	任务已结束且退款完成，可以用新的幂等键重新提交。
`succeeded 但下载失败`	先 HEAD output.video_url；如果非 200，把 task_id 发给平台排查下载链路。

NODE/v1/video/generations

Node.js 提交并轮询

适用于 Node.js 18+，API Key 从服务端环境变量读取。

const BASE_URL = "https://api.example.com";
const API_KEY = process.env.SEEAPI_API_KEY;

async function main() {
  const submit = await fetch(`${BASE_URL}/v1/video/generations`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "order-20260510-0001"
    },
    body: JSON.stringify({
      "model": "seedance-2.0",
      "prompt": "基于产品参考图生成一段自然柔光下的展示视频。",
      "reference_image_urls": [
            "asset://ref_image_xxx"
      ],
      "reference_video_urls": [
            "asset://ref_video_xxx"
      ],
      "reference_audio_urls": [
            "asset://ref_audio_mp3_xxx"
      ],
      "duration": 5,
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "count": 1,
      "mode": "mixed2video",
      "generate_audio": true,
      "search_enabled": true,
      "callback_url": "https://client.example.com/webhooks/seeapi"
})
  });

  const task = await submit.json();
  if (!submit.ok) throw new Error(JSON.stringify(task));

  while (true) {
    const res = await fetch(`${BASE_URL}/v1/tasks/${task.id}`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    });
    const current = await res.json();
    if (!res.ok) throw new Error(JSON.stringify(current));

    if (["succeeded", "refunded", "failed", "canceled"].includes(current.status)) {
      console.log(current);
      return;
    }
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

PYTHON/v1/video/generations

Python 提交并轮询

示例使用 requests；API Key 从服务端环境变量 SEEAPI_API_KEY 读取。

import os
import time
import requests

BASE_URL = "https://api.example.com"
API_KEY = os.environ["SEEAPI_API_KEY"]

payload = {
  "model": "seedance-2.0",
  "prompt": "基于产品参考图生成一段自然柔光下的展示视频。",
  "reference_image_urls": [
    "asset://ref_image_xxx"
  ],
  "reference_video_urls": [
    "asset://ref_video_xxx"
  ],
  "reference_audio_urls": [
    "asset://ref_audio_mp3_xxx"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "count": 1,
  "mode": "mixed2video",
  "generate_audio": True,
  "search_enabled": True,
  "callback_url": "https://client.example.com/webhooks/seeapi"
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": "order-20260510-0001",
}

submit = requests.post(f"{BASE_URL}/v1/video/generations", json=payload, headers=headers, timeout=30)
submit.raise_for_status()
task = submit.json()

while True:
    res = requests.get(
        f"{BASE_URL}/v1/tasks/{task['id']}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    res.raise_for_status()
    current = res.json()
    if current["status"] in ["succeeded", "refunded", "failed", "canceled"]:
        print(current)
        break
    time.sleep(3)