Doubao Seedance 视频生成 API 文档

概述

Seedance 系列视频生成模型（豆包）采用创建任务 → 轮询结果的异步调用模式：提交任务拿到任务 ID（id），再用任务 ID 轮询状态，直到 succeeded 后从响应里取视频地址。

报文用 content 数组：提示词与图片 / 视频 / 音频混在一个数组里，支持文生视频、图生视频（首帧、首尾帧）、参考生视频、视频延长与视频编辑。

计费说明

• 按输出 token 数结算，单价按「分辨率 × 是否包含视频输入」分档；成片时按实际上报用量收取（同一任务只结算一次）。
• 成片后会按实际上报的分辨率档位与时长校核费用，多退少补。
• 任务失败时，已扣费用自动原路退回，无需申请。
• 每次费用都会记入控制台「费用中心」，接口响应本身不返回费用。

模型列表

完整清单与各模型价格见模型广场。

调用流程

视频生成采用异步任务模式，分两步完成：

1. 提交任务：调用 POST /v1/videos/generations（或原生路径 POST /api/v3/contents/generations/tasks），返回任务 ID（id）
2. 轮询结果：调用 GET /v1/videos/generations/task/{taskId}（或原生路径 GET /api/v3/contents/generations/tasks/{taskId}）查询状态

双路径兼容：两条路径行为完全一致，可任选其一。

状态流转：

queued  ->  running  ->  succeeded / failed
queued / running 超过过期时间  ->  expired

一、提交视频生成任务

⚠️ QPS 限制：创建视频接口（含原生路径 /api/v3/contents/generations/tasks）默认 QPS 上限为 50。超过限制的请求将返回 429（code = RateLimitExceeded），请控制请求频率并实现退避重试。

1.1 请求地址

POST https://ai.jw-info.com/v1/videos/generations
POST https://ai.jw-info.com/api/v3/contents/generations/tasks    # 原生路径

两条路径行为完全一致，可任选其一。

1.2 请求头

1.3 请求参数

顶层参数

ratio 字段说明

可选值：16:9、4:3、1:1、3:4、9:16、21:9、adaptive（根据任务类型和输入内容自动适配宽高比）。不同模型的取值限制和 adaptive 适配规则如下：

不同分辨率、宽高比对应的高宽像素值

duration 字段说明

• Seedance 2.5：默认值 -1；取值范围 [4, 30]；或设置为 -1（智能选择）
• Seedance 2.0 系列：取值范围 [4, 15]；或设置为 -1（智能选择）

resolution 字段说明

• Seedance 2.5：默认值 720p；可选值 480p、720p
• Seedance 2.0：默认值 720p；可选值 480p、720p、1080p、4k
• Seedance 2.0 fast：默认值 720p；可选值 480p、720p
• Seedance 2.0 mini：默认值 720p；可选值 480p、720p

按档计价的模型请显式传 resolution：只传尺寸类字段时，接口会按短边自动补出档位再生成。

content 元素类型

每个元素通过 type 指定类型：

可选字段 role（素材角色）：

content 组合示例：

• 文生视频：text
• 图生视频：text（可选）+ image_url
• 多模态参考：text（可选）+ image_url / video_url / audio_url 组合

模型能力

各模型系列支持的生成模式与素材上限如下（每种模式均生成 1 个目标视频）。

Doubao Seedance 2.5（有声视频 / 无声视频）：

Doubao Seedance 2.0 系列（有声视频 / 无声视频）：

参数支持范围

上表即全部可用参数。方舟接口里仅 Seedance 1.0 系列支持的 frames、camera_fixed、service_tier 在本平台不适用（未上架 1.0 系列），传入会报错；omni_reference_task_type 与结果回调 callback_url 也不支持——任务类型由模型自动判定，结果请用查询接口轮询。

1.4 请求示例

样例 1：纯文生视频

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "一只橘猫在午后阳光下的窗台上打盹，微风吹动窗帘，镜头缓慢推进，温暖治愈风格"
    }
  ],
  "duration": 5,
  "ratio": "16:9",
  "generate_audio": false,
  "watermark": false
}

样例 2：图生视频（Base64 编码）

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "女孩抱着狐狸，女孩睁开眼，温柔地看向镜头，狐狸友善地抱着，镜头缓缓拉出，女孩的头发被风吹动"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "data:image/png;base64,aHR0******cG5n"
      }
    }
  ],
  "ratio": "adaptive",
  "duration": 5,
  "watermark": false
}

样例 3：有声视频 - 首尾帧

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {
      "type": "text",
      "text": "图中女孩对着镜头说“茄子”，360 度环绕运镜"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first_frame.jpeg"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/last_frame.jpeg"
      },
      "role": "last_frame"
    }
  ],
  "generate_audio": true,
  "ratio": "adaptive",
  "duration": 5,
  "watermark": false
}

样例 4：有声视频 - 首帧

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {
      "type": "text",
      "text": "女孩抱着狐狸，女孩睁开眼，温柔地看向镜头，镜头缓缓拉出，可以听到风声"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/i2v_first_frame.png"
      }
    }
  ],
  "generate_audio": true,
  "ratio": "adaptive",
  "duration": 5,
  "watermark": false
}

样例 5：延长视频

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {
      "type": "text",
      "text": "延长@视频1，窗户打开后进入@视频2的美术馆室内，最后镜头进入@视频3的画内"
    },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/extend_video1.mov" },
      "role": "reference_video"
    },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/extend_video2.mp4" },
      "role": "reference_video"
    },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/extend_video3.mp4" },
      "role": "reference_video"
    }
  ],
  "generate_audio": true,
  "ratio": "adaptive",
  "duration": 11,
  "output_format": "mov"
}

样例 6：编辑视频

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    { "type": "text", "text": "视频编辑：删除 @视频1中的所有人，除了主角。" },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/edit_input.mov" },
      "role": "reference_video"
    }
  ],
  "generate_audio": true,
  "ratio": "adaptive",
  "duration": -1,
  "output_format": "mov"
}

样例 7：多模态参考（图片 + 视频 + 音频）

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {
      "type": "text",
      "text": "参考@图像1的配色与@视频1的运镜，生成一段明亮多彩的产品短片，节奏感强"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference1.png" },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/reference2.mp4" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "https://example.com/reference_audio.mp3" },
      "role": "reference_audio"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 15
}

命令行（cURL）版：

curl https://ai.jw-info.com/v1/videos/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "一只橘猫在午后阳光下的窗台上打盹，镜头缓慢推进"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "watermark": false
  }'

1.5 响应参数

响应头里带 x-request-id；排查问题时提供该值即可定位本次请求。

1.6 响应示例

{
  "id": "cgt-20260826160420-Tcwwi"
}

提交成功后请保存 id，后续查询与对账都用它。

二、查询任务状态

2.1 请求地址

GET https://ai.jw-info.com/v1/videos/generations/task/{taskId}
GET https://ai.jw-info.com/api/v3/contents/generations/tasks/{taskId}    # 原生路径

两条路径行为完全一致，{taskId} 为提交任务返回的任务标识（cgt- 前缀）。

2.2 路径参数

2.3 请求示例

GET https://ai.jw-info.com/v1/videos/generations/task/cgt-20260826160420-Tcwwi
Authorization: Bearer sk-你的密钥

# 原生路径
GET https://ai.jw-info.com/api/v3/contents/generations/tasks/cgt-20260826160420-Tcwwi
Authorization: Bearer sk-你的密钥

2.4 响应参数

2.5 响应示例

生成成功（succeeded）：

{
  "id": "cgt-20260811223742-kz8z9",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/cgt-20260811223742-kz8z9.mp4"
  },
  "usage": {
    "completion_tokens": 38830,
    "total_tokens": 38830
  },
  "created_at": 1786459062,
  "updated_at": 1786459320,
  "duration": 4,
  "framespersecond": 24,
  "resolution": "480p",
  "ratio": "16:9",
  "seed": 10228,
  "generate_audio": true,
  "output_format": "mp4",
  "service_tier": "default",
  "execution_expires_after": 172800,
  "draft": false
}

处理中（running）：

{
  "id": "cgt-20260811223742-kz8z9",
  "model": "doubao-seedance-2-5-260628",
  "status": "running"
}

失败（failed）：

{
  "id": "cgt-20260811223742-kz8z9",
  "status": "failed",
  "error": {
    "code": "InvalidParameter",
    "message": "prompt is required"
  }
}

2.6 错误响应

错误体统一为方舟形状（code 见下方表格）：

{
  "error": {
    "code": "ResourceNotFound",
    "message": "The specified resource `cgt-20260826160420-Tcwwi` is not found. Request id: 1f0c5b8e9a2d4c6f8b0e1a3d5c7f9b2e",
    "param": "",
    "type": "NotFound"
  }
}

2.7 不提供的接口

任务列表与取消 / 删除接口不提供（模型服务只支持按任务 ID 查询）：

需要取消已提交的任务请忽略其结果；费用仅在成片时结算，失败会自动退回。

三、素材管理接口（通用约定）

视频生成常需引用参考图片 / 视频 / 音频。可以先把它们上传到素材库拿到 Id，生成时用 asset://<Id> 引用——素材可复用，源站 URL 失效也不用重传。

素材管理共 12 个 Action（素材组 5 个、素材 5 个、真人认证 2 个），只服务 Seedance 系列。

3.1 接口概述

• 全部 12 个操作共用同一个地址，通过 Query 参数 Action 与固定版本号 Version 分发。
• 创建素材（CreateAsset）是异步接口：返回成功只表示已受理，需轮询 GetAsset 或 ListAssets 查看状态（Processing / Active / Failed）。视频类素材处理时间更长，不承诺处理时长。
• 素材类型支持图像、视频、音频，仅支持公网可访问的 URL，不支持 Base64。
• 素材组与素材的 ID 形如 group-20240514212750-b5e9m、asset-20240514212750-a3f8k，请直接使用接口返回值。

3.2 统一入口（接口地址）

POST https://ai.jw-info.com/?Action={Action}&Version=2024-01-01
POST https://ai.jw-info.com/v1/api/asset?Action={Action}&Version=2024-01-01

两条地址行为完全一致。 Version 固定为 2024-01-01；传其它值会返回 400 InvalidParameter。

3.3 请求头

3.4 鉴权

素材库支持两种凭证，两种都对应同一个账号的素材空间：

1. AK/SK（推荐）

• 调用只校验 AK、不校验签名：Signature、X-Date、X-Content-Sha256 可以随意填，日期段、Region、Service 也不参与校验；
• AK 不通用：方舟官方的 AK 不能直接用于本平台，请使用本平台控制台申请的 AK/SK；
• AK/SK 在控制台「密钥管理」申请，可以一键复制或导出 CSV；Secret Access Key 只显示一次，请立即保存；
• 为方便 curl 手调，也接受自定头 x-ak: <你的 AK>（与签名头等价）。

curl -X POST "https://ai.jw-info.com/?Action=ListAssetGroups&Version=2024-01-01" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 Credential=AKXXXXXXXX/20240514/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=any' \
  -d '{"Filter":{"GroupType":"AIGC"},"PageNumber":1,"PageSize":10}'

2. API Key（兼容）

在请求头里带 Authorization: Bearer <你的 API Key>（或 x-api-key），与平台其它接口一致，无需签名。

两种凭证的素材空间按账号划分（同一账号的 AK 与 API Key 看到的是同一批素材）。不同账号之间相互不可见、不可修改。

3.5 通用响应结构

成功响应统一为两层结构：ResponseMetadata 描述本次请求，Result 承载业务数据。

{
  "ResponseMetadata": {
    "RequestId": "20240514212750B2C3D4E5F6789ABCDE",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Id": "group-20240514212750-b5e9m"
  }
}

请求级错误放在 ResponseMetadata.Error（Code / Message），HTTP 状态码同步给出。

{
  "ResponseMetadata": {
    "RequestId": "20240514212750A1B2C3D4E5F6789ABC",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Error": {
      "Code": "NotFound",
      "Message": "asset not found"
    }
  }
}

3.6 Action 列表速览

3.7 分页

列表接口（ListAssetGroups、ListAssets）支持两种分页方式，只能任选其一，不可同时传入两类参数。

方式一：NextToken 分页（推荐）

• 首次查询传 MaxResults 设置每页记录数（默认 10），无需传 NextToken；存在下一页时响应返回 NextToken。
• 后续查询传入上一次返回的 NextToken；未返回 NextToken 表示遍历结束。
• 该方式不返回 TotalCount、PageNumber、PageSize。
• 翻页时建议保持 Filter、ProjectName、SortBy、SortOrder 与首次查询一致。

方式二：页码分页（兼容）

• 通过 PageNumber 与 PageSize 指定页码与每页记录数（两者需同时使用），响应返回 TotalCount、PageNumber、PageSize。
• 当 PageSize * PageNumber > 20000（素材组为 10000）时，请改用 NextToken 深翻页。

四、素材组管理（AssetGroup）

4.1 创建素材资产组合（CreateAssetGroup）

创建 Asset Group（素材资产组合），用作素材资产管理。

请求参数

响应参数

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=CreateAssetGroup&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Name": "demo-portrait-group",
    "Description": "虚拟人像素材组示例",
    "GroupType": "AIGC",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "20240514212750B2C3D4E5F6789ABCDE",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Id": "group-20240514212750-b5e9m"
  }
}

4.2 查询素材资产组合列表（ListAssetGroups）

请求参数

响应参数

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=ListAssetGroups&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Filter": {
        "GroupIds": ["group-20240514212750-b5e9m"],
        "GroupType": "AIGC"
    },
    "MaxResults": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "202405142130002B3C4D5E6F70819203",
    "Action": "ListAssetGroups",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Items": [
      {
        "Id": "group-20240514212750-b5e9m",
        "Name": "demo-portrait-group",
        "Description": "虚拟人像素材组示例",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreateTime": "2024-05-14T21:27:50Z",
        "UpdateTime": "2024-05-14T21:30:00Z"
      }
    ],
    "NextToken": "****bmNyeXB0ZWRfY3Vyc29yIjoiLi4****"
  }
}

4.3 查询素材资产组合信息（GetAssetGroup）

请求参数

响应参数

CreateTime、Description、GroupType、Id、Name、ProjectName、UpdateTime，含义同「查询素材资产组合列表」的 Items 字段。

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=GetAssetGroup&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Id": "group-20240514212750-b5e9m",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "20240514213000F6789ABCDEF0123456",
    "Action": "GetAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Id": "group-20240514212750-b5e9m",
    "Name": "demo-portrait-group",
    "Description": "虚拟人像素材组示例",
    "GroupType": "AIGC",
    "ProjectName": "default",
    "CreateTime": "2024-05-14T21:27:50Z",
    "UpdateTime": "2024-05-14T21:30:00Z"
  }
}

4.4 更新素材资产组合信息（UpdateAssetGroup）

请求参数

响应参数

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=UpdateAssetGroup&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Id": "group-20240514212750-b5e9m",
    "Name": "demo-portrait-group-renamed",
    "Description": "更新后的虚拟人像素材组描述",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "202405142130004D5E6F708192031A2B",
    "Action": "UpdateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Id": "group-20240514212750-b5e9m"
  }
}

4.5 删除素材资产组（DeleteAssetGroup）

删除素材组时，组内素材一并删除。

请求参数

响应参数

本接口无特有返回参数，成功时 Result 为空对象 {}。

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=DeleteAssetGroup&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Id": "group-20240514212750-b5e9m",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "20240514213000D4E5F6789ABCDEF012",
    "Action": "DeleteAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {}
}

五、素材管理（Asset）

5.1 创建素材资产（CreateAsset）

在指定的 Asset Group 内传入 Asset（素材资产）。

注意：本接口为异步接口，系统处理可能出现排队。返回成功只表示已受理，请轮询 GetAsset 确认 Status 变为 Active 后再用于推理。

请求参数

格式要求

• 图像：格式 jpeg、png、webp、bmp、tiff、gif、heic、heif；宽高比 (0.4, 2.5)；宽高长度 (300, 6000) px；单张小于 30 MB
• 视频：格式 mp4、mov；分辨率 480p、720p、1080p、4K；时长 [2, 30] s；宽高比 [0.4, 2.5]；宽高长度 [300, 6000] px；总像素数 ∈ [407696, 8295044]；单个不超过 200 MB；帧率 [24, 60]
• 音频：格式 wav、mp3；时长 [2, 30] s；单个不超过 15 MB

响应参数

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=CreateAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "GroupId": "group-20240514212750-b5e9m",
    "URL": "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/demo.png",
    "Name": "demo-portrait-image",
    "AssetType": "Image",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "20240514212750A1B2C3D4E5F6789ABC",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Id": "asset-20240514212750-a3f8k"
  }
}

5.2 查询素材资产列表（ListAssets）

请求参数

响应参数

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=ListAssets&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Filter": {
        "GroupIds": ["group-20240514212750-b5e9m"],
        "GroupType": "AIGC",
        "Statuses": ["Active"]
    },
    "MaxResults": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "202405142130001A2B3C4D5E6F708192",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Items": [
      {
        "Id": "asset-20240514212750-a3f8k",
        "Name": "demo-portrait-image",
        "URL": "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/asset-20240514212750-a3f8k.png?Expires=43200",
        "GroupId": "group-20240514212750-b5e9m",
        "AssetType": "Image",
        "Status": "Active",
        "Moderation": {
          "Strategy": "Default"
        },
        "Error": {
          "Code": "",
          "Message": ""
        },
        "ProjectName": "default",
        "CreateTime": "2024-05-14T21:27:50Z",
        "UpdateTime": "2024-05-14T21:30:00Z",
        "LastInferenceTime": "2024-05-14T22:15:30Z"
      }
    ],
    "NextToken": "****bmNyeXB0ZWRfY3Vyc29yIjoiLi4****"
  }
}

5.3 查询素材资产信息（GetAsset）

查询素材资产状态，确认素材是否已完成预处理并可用于推理。

注意：查询到上传失败的素材时，接口仍可能返回 200，此时需通过 Status = Failed 与 Error.Code / Error.Message 获取失败原因。

请求参数

响应参数

AssetType、CreateTime、Error、Error.Code、Error.Message、GroupId、Id、LastInferenceTime、Moderation、Moderation.Strategy、Name、ProjectName、Status、UpdateTime、URL，含义同「查询素材资产列表」的 Items 字段。

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=GetAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Id": "asset-20240514212750-a3f8k",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "20240514213000E5F6789ABCDEF01234",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Id": "asset-20240514212750-a3f8k",
    "Name": "demo-portrait-image",
    "URL": "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/asset-20240514212750-a3f8k.png?Expires=43200",
    "AssetType": "Image",
    "GroupId": "group-20240514212750-b5e9m",
    "Status": "Active",
    "Moderation": {
      "Strategy": "Default"
    },
    "Error": {
      "Code": "",
      "Message": ""
    },
    "CreateTime": "2024-05-14T21:27:50Z",
    "UpdateTime": "2024-05-14T21:30:00Z",
    "LastInferenceTime": "2024-05-14T22:15:30Z",
    "ProjectName": "default"
  }
}

5.4 更新素材资产信息（UpdateAsset）

当前仅支持更新 Name。

请求参数

响应参数

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=UpdateAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Id": "asset-20240514212750-a3f8k",
    "Name": "demo-portrait-image-renamed",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "202405142130003C4D5E6F708192031A",
    "Action": "UpdateAsset",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "Id": "asset-20240514212750-a3f8k"
  }
}

5.5 删除素材资产（DeleteAsset）

请求参数

响应参数

本接口无特有返回参数，成功时 Result 为空对象 {}。

请求示例

curl 'https://ai.jw-info.com/v1/api/asset?Action=DeleteAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -d '{
    "Id": "asset-20240514212750-a3f8k",
    "ProjectName": "default"
}'

响应示例

{
  "ResponseMetadata": {
    "RequestId": "20240514213000C3D4E5F6789ABCDEF0",
    "Action": "DeleteAsset",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {}
}

六、视觉校验（VisualValidate）

以下两个接口用于真人素材（LivenessFace）的认证与素材组获取。终端客户在 H5 页面完成认证后，CallbackURL 会带上结果参数（resultCode 为 10000 表示检测成功），凭其中的 bytedToken 即可换取素材组 ID。

凭证有两种写法都能用：本接口返回的 BytedToken（形如 vvs-20240514212750-c8f2p），以及回调地址里 bytedToken 参数的值。同一凭证只能换一次素材组，重复调用会返回同一个组。

6.1 拉起真人认证 H5（CreateVisualValidateSession）

拉起端上 H5 真人认证页链接。终端客户使用 H5Link 完成真人认证，点击"完成"后打开 CallbackURL，可通过解析 CallbackURL 后拼接的 resultCode 参数获取认证结果（resultCode 为 10000 表示检测成功）。

回调地址拼接的参数：

<CallbackURL>?bytedToken=&resultCode=10000&algorithmBaseRespCode=0&reqMeasureInfoValue=1&verify_type=real_time

请求参数

响应参数

响应示例

{
  "ResponseMetadata": {
    "RequestId": "202405142130005E6F708192031A2B3C",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "BytedToken": "vvs-20240514212750-c8f2p",
    "H5Link": "https://example.com/verify/h5?byted_token=vvs-20240514212750-c8f2p&lng=zh",
    "CallbackURL": "https://your-domain.example.com/callback"
  }
}

6.2 获取真人 Asset Group ID（GetVisualValidateResult）

真人认证通过后（resultCode 返回 10000），通过本接口获取本次认证创建的素材组 ID。

请求参数

响应参数

响应示例

{
  "ResponseMetadata": {
    "RequestId": "202405142130006F708192031A2B3C4D",
    "Action": "GetVisualValidateResult",
    "Version": "2024-01-01",
    "Service": "ark"
  },
  "Result": {
    "GroupId": "group-20240514212750-b5e9m"
  }
}

七、视频生成中的 asset:// 引用

视频生成接口（POST https://ai.jw-info.com/v1/videos/generations，或原生路径 POST https://ai.jw-info.com/api/v3/contents/generations/tasks）的 content 数组里，可以用 asset://<Id> 引用素材库里已就绪的素材，替代公网 URL；引用不合法时接口直接返回错误，不会提交生成任务。

7.1 三种引用写法

{"type":"image_url","role":"reference_image","image_url":{"url":"asset://asset-20240514212750-a3f8k"}}

{"type":"video_url","role":"reference_video","video_url":{"url":"asset://<Id>"}}

{"type":"audio_url","role":"reference_audio","audio_url":{"url":"asset://<Id>"}}

三种素材角色：图片（reference_image / first_frame / last_frame）、视频（reference_video）、音频（reference_audio）。

7.2 归属校验行为

{
  "error": {
    "message": "asset not owned by key: [\"asset-20240514212750-a3f8k\"]",
    "type": "invalid_request_error",
    "code": "forbidden"
  }
}

7.3 端到端示例（建组 → 建素材 → 轮询 Active → 视频生成）

GATEWAY="https://ai.jw-info.com"
API_KEY="sk-你的密钥"

# 1. 创建素材组
GROUP_ID=$(curl -s -X POST "${GATEWAY}/v1/api/asset?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" -H "Authorization: Bearer ${API_KEY}" \
  -d '{"Name":"视频素材组","GroupType":"AIGC"}' | jq -r '.Result.Id')
echo "组 ID: ${GROUP_ID}"

# 2. 创建素材（图片）
ASSET_ID=$(curl -s -X POST "${GATEWAY}/v1/api/asset?Action=CreateAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" -H "Authorization: Bearer ${API_KEY}" \
  -d "{\"GroupId\":\"${GROUP_ID}\",\"URL\":\"https://example.com/cat.jpg\",\"AssetType\":\"Image\",\"Name\":\"猫咪\"}" \
  | jq -r '.Result.Id')
echo "素材 ID: ${ASSET_ID}"

# 3. 轮询素材就绪（Status=Active）
while true; do
  STATUS=$(curl -s -X POST "${GATEWAY}/v1/api/asset?Action=GetAsset&Version=2024-01-01" \
    -H "Content-Type: application/json" -H "Authorization: Bearer ${API_KEY}" \
    -d "{\"Id\":\"${ASSET_ID}\"}" | jq -r '.Result.Status')
  echo "素材状态: ${STATUS}"
  [ "${STATUS}" = "Active" ] && break
  sleep 5
done

# 4. 提交视频生成任务，用 asset:// 引用素材
TASK_ID=$(curl -s -X POST "${GATEWAY}/v1/videos/generations" \
  -H "Content-Type: application/json" -H "Authorization: Bearer ${API_KEY}" \
  -d "{\"model\":\"doubao-seedance-2-5-260628\",\"content\":[{\"type\":\"text\",\"text\":\"图片1 一只猫在花园里奔跑\"},{\"type\":\"image_url\",\"role\":\"reference_image\",\"image_url\":{\"url\":\"asset://${ASSET_ID}\"}}],\"duration\":5}" \
  | jq -r '.id')
echo "任务 ID: ${TASK_ID}"

# 5. 轮询视频生成结果
while true; do
  RESULT=$(curl -s "${GATEWAY}/v1/videos/generations/task/${TASK_ID}" \
    -H "Authorization: Bearer ${API_KEY}")
  STATUS=$(echo "${RESULT}" | jq -r '.status')
  echo "任务状态: ${STATUS}"
  if [ "${STATUS}" = "succeeded" ]; then
    echo "视频 URL: $(echo "${RESULT}" | jq -r '.content.video_url')"
    break
  elif [ "${STATUS}" = "failed" ]; then
    echo "失败: $(echo "${RESULT}" | jq -r '.error.message')"
    break
  fi
  sleep 10
done

八、错误响应

错误响应统一为方舟形状：{"error":{"code","message","param","type"}}；响应头里带 x-request-id（排查问题时提供它可快速定位）。

示例（参数缺失）：

{
  "error": {
    "code": "MissingParameter",
    "message": "The parameter `model` is required.",
    "param": "model",
    "type": "Bad Request"
  }
}

示例（任务查不到）：

{
  "error": {
    "code": "ResourceNotFound",
    "message": "The specified resource `cgt-20260826160420-Tcwwi` is not found. Request id: 1f0c5b8e9a2d4c6f8b0e1a3d5c7f9b2e",
    "param": "",
    "type": "NotFound"
  }
}

超过创建视频接口 QPS 限制（默认 50）时返回 429：

{
  "error": {
    "code": "RateLimitExceeded",
    "message": "调用过于频繁，请稍后重试",
    "param": "",
    "type": "Too Many Requests"
  }
}

任务本身失败（如素材不可访问、内容不合规）时，查询响应里的 status 为 failed，失败原因见 error.code / error.message；已扣费用自动退回。

8.1 素材接口错误

素材接口（/v1/api/asset）的错误体是方舟形状——错误放在 ResponseMetadata.Error：

而视频生成接口里 asset:// 引用校验失败沿用文档错误体：

素材处理失败（Status = Failed）时接口仍返回 200，失败原因在 Error.Code / Error.Message：

创建或查询素材时，Status 为 Failed 的素材会带 Error.Code 与 Error.Message：

请求级错误（参数缺失、ID 不存在、不属于当前账号等）通过 HTTP 状态码与 ResponseMetadata.Error 返回，常见 Code：InvalidParameter、NotFound、InvalidApiKey、InsufficientBalance、UnsupportedAction。

平台侧错误（密钥无效 401、余额不足 403、模型未上架 404 等）的完整状态码见「错误码」页。

九、代码示例

以下示例统一使用 /v1/* 兼容路径；两条路径行为一致，把示例中的 /v1/videos/generations 替换为 /api/v3/contents/generations/tasks、/v1/videos/generations/task/{id} 替换为 /api/v3/contents/generations/tasks/{id} 即可改用原生路径。

9.1 cURL

# 1. 提交任务
TASK_ID=$(curl -s -X POST https://ai.jw-info.com/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "一只橘猫在午后阳光下的窗台上打盹，微风吹动窗帘，镜头缓慢推进"
      }
    ],
    "duration": 5,
    "ratio": "16:9",
    "watermark": false
  }' | jq -r '.id')

echo "任务ID: $TASK_ID"

# 2. 轮询任务状态
while true; do
  sleep 10
  RESULT=$(curl -s "https://ai.jw-info.com/v1/videos/generations/task/$TASK_ID" \
    -H "Authorization: Bearer sk-你的密钥")

  STATUS=$(echo "$RESULT" | jq -r '.status // empty')
  echo "当前状态: $STATUS"

  if [ "$STATUS" = "succeeded" ]; then
    echo "视频 URL:"
    echo "$RESULT" | jq -r '.content.video_url // empty'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "任务失败"
    break
  fi
done

9.2 Python - requests

import time
import requests

BASE = "https://ai.jw-info.com"
API_KEY = "sk-你的密钥"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

# 1. 提交任务
payload = {
    "model": "doubao-seedance-2-0-260128",
    "content": [
        {"type": "text", "text": "一只橘猫在午后阳光下的窗台上打盹，镜头缓慢推进"}
    ],
    "duration": 5,
    "ratio": "16:9",
}
response = requests.post(f"{BASE}/v1/videos/generations", json=payload, headers=HEADERS)
result = response.json()
if response.status_code != 200:
    print("提交任务失败:", result.get("error", {}).get("message", result))
    raise SystemExit(1)

task_id = result["id"]
print(f"任务已提交，ID: {task_id}")

# 2. 轮询任务状态
while True:
    time.sleep(10)
    result = requests.get(f"{BASE}/v1/videos/generations/task/{task_id}",
                          headers=HEADERS).json()
    status = result.get("status")
    print(f"当前状态: {status}")
    if status == "succeeded":
        print("视频 URL:", result["content"]["video_url"])
        print("分辨率:", result["usage"]["SR"], "时长:", result["usage"]["duration"], "秒")
        break
    if status == "failed":
        print("任务失败:", result.get("error"))
        break

9.3 Java - OkHttp

import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;

public class SeedanceVideoExample {
    private static final String GATEWAY = "https://ai.jw-info.com";
    private static final String API_KEY = "sk-你的密钥";
    private static final OkHttpClient CLIENT = new OkHttpClient();
    private static final ObjectMapper MAPPER = new ObjectMapper();

    public static void main(String[] args) throws Exception {
        // 1. 提交任务
        String createJson = """
            {
              "model": "doubao-seedance-2-0-260128",
              "content": [
                { "type": "text", "text": "城市夜景航拍，霓虹灯闪烁，车流如织" }
              ],
              "duration": 5,
              "ratio": "16:9"
            }
        """;

        Request createRequest = new Request.Builder()
            .url(GATEWAY + "/v1/videos/generations")
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + API_KEY)
            .post(RequestBody.create(createJson, MediaType.get("application/json")))
            .build();

        try (Response resp = CLIENT.newCall(createRequest).execute()) {
            String body = resp.body().string();
            String taskId = MAPPER.readTree(body).at("/id").asText();
            System.out.println("任务已提交, ID: " + taskId);

            // 2. 轮询任务状态
            String queryUrl = GATEWAY + "/v1/videos/generations/task/" + taskId;
            while (true) {
                Thread.sleep(10000);
                Request queryRequest = new Request.Builder()
                    .url(queryUrl)
                    .header("Authorization", "Bearer " + API_KEY)
                    .get()
                    .build();

                try (Response qResp = CLIENT.newCall(queryRequest).execute()) {
                    var json = MAPPER.readTree(qResp.body().string());
                    String status = json.at("/status").asText();
                    System.out.println("当前状态: " + status);
                    if ("succeeded".equals(status)) {
                        System.out.println("视频 URL: " + json.at("/content/video_url").asText());
                        break;
                    } else if ("failed".equals(status)) {
                        System.out.println("任务失败");
                        break;
                    }
                }
            }
        }
    }
}

十、注意事项

• ⚠️ 时效限制：任务记录与视频下载地址都有时效（由模型服务提供），请及时下载转存；不要把任务号当长期存储。
• 轮询间隔：建议 5–15 秒轮询一次，避免过于频繁。
• ⚠️ QPS 限制：创建视频接口默认 QPS 上限为 50，超限返回 429（code = RateLimitExceeded），请做好退避重试。
• ⚠️ 不提供的接口：任务列表与取消/删除接口不提供（调用返回 404 ResourceNotFound）；任务不能中途取消，请忽略结果即可。
• 素材引用规则：在 type: "text" 中，按 content 数组顺序从 1 开始编号，使用 图片N / 视频N / 音频N 引用对应素材（如 图片1、视频1、音频1，不带方括号，中文写法）。
• 素材地址：图片与参考视频请使用公网可访问的 URL；图片也支持 Base64（data:image/png;base64,...）。
• 分辨率与计费：按档计价的模型成片后按实际出片档位与时长校核费用，多退少补；想指定档位请显式传 resolution。
• 文件不落盘：接口只返回视频地址，不保存文件本体，请及时转存。
• 素材 URL 有效期 12 小时：GetAsset / ListAssets 返回的 URL 是临时地址，请及时保存或转存到你自己的存储。
• 素材组与素材只能被创建它们的账号访问（AK 与 API Key 同属一个账号）；换账号查不到、也改不了别人的素材。
• 创建素材是异步的：CreateAsset 返回成功不代表可用，请轮询 GetAsset 直到 Status 为 Active。
• 删除素材组会级联删除组内素材，请谨慎操作。
• 素材名称仅用于检索：Name 不会被带入模型推理。

---

相关能力：模型广场｜视频生成模型