diff --git a/docs/API文档/3-28-【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）.md b/docs/API文档/3-28-【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）.md new file mode 100644 index 0000000..8b55529 --- /dev/null +++ b/docs/API文档/3-28-【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）.md @@ -0,0 +1,961 @@ +# 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版） + +该文档目前仅限开白客户使用，发送前请和销管确认客户是否在开白名单内 + +***【❗️❗️❗️】该文档限制客户申请权限，只有返回了服务协议的客户方可申请*** + +本文介绍 Seedance 2.0 & 2.0 fast 模型相较于存量模型 **新增/配置有区别 **的 API 参数介绍，存量 API 参数的完整介绍参见 [视频生成 API](https://www.volcengine.com/docs/82379/1520758?lang=zh)。 + +> 本文档仅限预览及邀测用户使用： +> +> * 不承诺正式API上线100%一致。 +> +> * 仅限邀测用户阅读，请勿截图/分享给其他人员。 +> +> * 您上传的内容请确保由您原创或已取得授权。 + +# 模型能力 + +> **Seedance 2.0 和 Seedance 2.0 fast 提供的模型能力一致，**追求最高生成品质，推荐使用 **Seedance 2.0**；更注重成本与生成速度，不要求极限品质，推荐使用 **Seedance 2.0 fast**。 + +**Seedance 2.0 & 2.0 fast (有声视频/无声视频)** + +* **多模态参考生视频**：输入参考图片（0\~9）+参考视频（0\~3）+ 参考音频（0\~3）+ 文本提示词（可选）生成 1 个目标视频。支持生成全新视频、编辑视频、延长视频。 + +> **注意：不可单独输入音频，应至少包含 1 个参考视频或图片。** + +* **图生视频-首尾帧**：输入首帧图片+尾帧图片+文本提示词（可选）生成 1 个目标视频。 + +* **图生视频-首帧**：输入首帧图片+文本提示词（可选）生成 1 个目标视频。 + +* **文生视频**：输入文本提示词生成 1 个目标视频。 + + + +**模型能力对比表：** + +| 模型名称 | | [Seedance 2.0](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-2-0) | [Seedance 2.0 fast](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-2-0-fast\&projectName=default) | [Seedance 1.5 pro](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-5-pro\&projectName=default) | [Seedance 1.0 pro ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-pro\&projectName=default) | [Seedance 1.0 pro fast ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-pro-fast\&projectName=default) | [Seedance 1.0 lite i2v](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-lite-i2v\&projectName=default) | [Seedance-1.0 lite t2v ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-lite-t2v) | +| ------------ | -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Model ID | | doubao-seedance-2-0-260128 | doubao-seedance-2-0-fast-260128 | doubao-seedance-1-5-pro-251215 | doubao-seedance-1-0-pro-250528 | doubao-seedance-1-0-pro-fast-251015 | doubao-seedance-1-0-lite-i2v-250428 | doubao-seedance-1-0-lite-t2v-250428 | +| 文生视频 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ | +| 图生视频-首帧 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ❌ | +| 图生视频-首尾帧 | | ✅ | | ✅ | ✅ | ❌ | ✅ | ❌ | +| 多模态参考【New】 | 图片参考 | ✅ | | ❌ | ❌ | ❌ | ✅ | ❌ | +| | 视频参考 | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ | +| | 组合参考 | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ | +| 编辑视频【New】 | | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ | +| 延长视频【New】 | | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ | +| 生成有声视频 | | ✅ | | ✅ | ❌ | ❌ | ❌ | ❌ | +| 联网搜索增强【New】 | | ✅ | | ❌ | [❌](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f359753773c94d97885008ca1223c9bc) | ❌ | ❌ | ❌ | +| 样片模式 | | ❌ | | ✅ | ❌ | ❌ | ❌ | ❌ | +| 返回视频尾帧 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ | +| 输出视频规格 | 输出分辨率 | 480p, 720p | | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | +| | 输出宽高比 | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | | | | | | | +| | 输出时长 | 4\~15 秒 | | 4\~12 秒 | 2\~12 秒 | 2\~12 秒 | 2\~12 秒 | 2\~12 秒 | +| | 输出视频格式 | mp4 | | mp4 | mp4 | mp4 | mp4 | mp4 | +| 离线推理 | | [❌](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f359753773c94d97885008ca1223c9bc) | | ✅ | ✅ | ✅ | ✅ | ✅ | +| 在线推理限流 | RPM | 600 | | 600 | 600 | 600 | 300 | 300 | +| | 并发数 | 10 | | 10 | 10 | 10 | 5 | 5 | +| 离线推理限流 | TPD | - | | 5000亿 | 5000亿 | 5000亿 | 2500亿 | 2500亿 | + + + + + +# Creat-创建视频生成任务 + +> POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks + +## 请求参数 + + + +#### **content** `object[]` `必选` + +输入给模型，生成视频的信息，支持文本、图片、音频、视频、样片任务 ID。支持以下几种组合： + +* **文本** + +* **文本（可选）+ 图片** + +* **文本（可选）+ 视频** + +* **文本（可选）+ 图片 + 音频** + +* **文本（可选）+ 图片 + 视频** + +* **文本（可选）+ 视频 + 音频** + +* **文本（可选）+ 图片 + 视频 + 音频** + +*** + +**信息类型：** + +* **文本信息**`object` + +输入给模型的提示词信息。 + +*** + +content.**type **`string` `必选` + +输入内容的类型，此处应为 **text**。 + +*** + +content.**text **`string` `必选` + +输入给模型的文本提示词，描述期望生成的视频。 + +支持中英文。建议中文不超过500字，英文不超过1000词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成视频缺失部分元素。提示词的更多使用技巧请参见 [Seedance 提示词指南](https://www.volcengine.com/docs/82379/1587797)。 + + + + + +* **图片信息** `object` + +输入给模型的图片信息。 + +*** + +content.**type **`string` `必选` + +输入内容的类型，此处应为 **image\_url**。 + +*** + +content.**image\_url **`object` `必选` + +输入给模型的图片对象。 + +*** + +content.image\_url.**url **`string` `必选` + +图片 URL 、图片 Base64 编码、素材 ID。 + +* 图片 URL：填入图片的公网 URL。 + +* Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式：data:image/<图片格式>;base64,\，注意 <图片格式> 需小写，如 data:image/png;base64,{base64\_image}。 + +* 素材 ID：用于视频生成的预置素材及虚拟人像的 ID，遵循格式：asset://\，可从 [素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128) 获取，详细使用请参见[文档](https://www.volcengine.com/docs/82379/2223965?lang=zh)。 + +> **传入单张图片要求** +> +> * 格式：jpeg、png、webp、bmp、tiff、gif +> +> * 宽高比（宽/高）： (0.4, 2.5) +> +> * 宽高长度（px）：(300, 6000) +> +> * 大小：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用Base64编码。 +> +> * 图片数量： +> +> * 图生视频-首帧：1 张 +> +> * 图生视频-首尾帧：2 张 +> +> * Seedance 2.0 & 2.0 fast 多模态参考生视频：1\~9 张 + +*** + +content.**role **`string` `条件必填` + +图片的位置或用途。 + +> **注意** +> +> * **图生视频-首帧**、**图生视频-首尾帧**、**多模态参考生视频**（包括参考图、视频、音频）为 3 种互斥场景，**不可混用**。 +> +> * **多模态参考生视频**可通过提示词指定参考图片作为首帧/尾帧，间接实现“首尾帧+多模态参考”效果。若需严格保障首尾帧和指定图片一致，**优先使用图生视频-首尾帧**（配置 role 为 **first\_frame / last\_frame**）。 + +*** + +**图生视频-首帧** + +> 需要传入1个 image\_url 对象 + +* **字段role取值：** + + * **first\_frame 或不填** + +*** + +**图生视频-首尾帧** + +> 需要传入2个 image\_url 对象 + +* **字段role取值：** + + * 首帧图片对应的字段 role 为：**first\_frame**，必填 + + * 尾帧图片对应的字段 role 为：**last\_frame**，必填 + +*** + +**图生视频-参考图 ** + +> 可传入 1\~9 个 image\_url 对象 + +* **字段role取值**： + + * 每张参考图对应的字段 role 均为：**reference\_image**，必填 + + + + + +* **视频信息** `object` + +输入给模型的视频信息。仅 Seedance 2.0 & 2.0 fast 支持输入视频。2026年3月11日起，支持使用本账号下 Seedance 2.0 & 2.0 fast 模型产出的视频作为输入素材，进行视频编辑或延长，其中的真人人脸可正常使用，不会触发审核拦截。 + +*** + +content.**type **`string` `必选` + +输入内容的类型，此处应为 **video\_url**。 + +*** + +content.**video\_url **`object` `必选` + +输入给模型的视频对象。 + +*** + +content.video\_url.**url **`string` `必选` + +视频URL、素材 ID。 + +* 视频 URL：填入视频的公网 URL。 + +* 素材 ID：用于视频生成的预置素材及虚拟人像视频的 ID，遵循格式：asset://\。可从[素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128)获取。 + +> **传入单个视频要求** +> +> * 视频格式：mp4、mov。 +> +> * 分辨率：480p、720p +> +> * 时长：单个视频时长 \[2, 15] s，最多传入 3 个参考视频，所有视频总时长不超过 15s。 +> +> * 尺寸： +> +> * 宽高比（宽/高）：\[0.4, 2.5] +> +> * 宽高长度（px）：\[300, 6000] +> +> * 画面像素（宽 × 高）：\[409600, 927408] ，示例： +> +> * 画面尺寸 640×640=409600 满足最小值 ； +> +> * 画面尺寸 834×1112=927408 满足最大值。 +> +> * 大小：单个视频不超过 50 MB。 +> +> * 帧率 (FPS)：\[24, 60] + +*** + +content.**role **`string` `条件必填` + +视频的位置或用途。当前仅支持 **reference\_video**。 + + + + + +* **音频信息 **`object` + +输入给模型的音频信息。仅 Seedance 2.0 & 2.0 fast 支持输入音频。注意不可单独输入音频，应至少包含 1 个参考视频或图片。 + +*** + +content.**type **`string` `必选` + +输入内容的类型，此处应为 **audio\_url**。 + +*** + +content.**audio\_url **`object` `必选` + +输入给模型的音频对象。 + +*** + +content.audio\_url.**url **`string` `必选` + +音频 URL 、音频 Base64 编码、素材 ID。 + +* 音频 URL：填入音频的公网 URL。 + +* Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式：data:audio/<音频格式>;base64,\，注意 <音频格式> 需小写，如 data:audio/wav;base64,{base64\_audio}。 + +* 素材 ID：用于视频生成的虚拟人的音频素材 ID，遵循格式：asset://\。可从[素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128)获取。 + +> **传入单个音频要求** +> +> * 格式：wav、mp3 +> +> * 时长：单个音频时长 \[2, 15] s，最多传入 3 段参考音频，所有音频总时长不超过 15 s。 +> +> * 大小：单个音频不超过 15 MB，请求体大小不超过 64 MB。大文件请勿使用Base64编码。 + +*** + +content.**role **`string` `条件必填` + +音频的位置或用途。当前仅支持 **reference\_audio** 。 + + + +#### **service\_tier** `string` + + Seedance 2.0 & 2.0 fast 暂不支持 + + + +#### **generate\_audio **`boolean` + +> Seedance 2.0 & 2.0 fast 默认值： true + +控制生成的视频是否包含与画面同步的声音。 + +* true：模型输出的视频包含同步音频。模型会基于文本提示词与视觉内容，自动生成与之匹配的人声、音效及背景音乐。建议将对话部分置于双引号内，以优化音频生成效果。例如：男人叫住女人说：“你记住，以后不可以用手指指月亮。” + +* false：模型输出的视频为无声视频。 + +> **说明** +> +> 生成的有声视频均为单声道，和传入的音频声道数无关。 + +#### + +#### **draft **`boolean` + + Seedance 2.0 & 2.0 fast 暂不支持 + + + +#### **tools **`object[]` + +> 仅 Seedance 2.0 & 2.0 fast 支持 + +配置模型要调用的工具。 + +*** + +tools.**type **`string` + +指定使用的工具类型。 + +* web\_search：联网搜索工具。当前仅文生视频支持。 + +> **说明** +> +> * 开启联网搜索后，模型会根据用户的提示词自主判断是否搜索互联网内容（如商品、天气等）。可提升生成视频的时效性，但也会增加一定的时延。 +> +> * 实际搜索次数可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 usage.tool\_usage.**web\_search** 字段获取，如果为 0 表示未搜索。 + + + +#### **resolution ** `string` + +> Seedance 2.0 & 2.0 fast 默认值：720p + +视频分辨率，取值范围： + +* 480p + +* 720p + + + +#### **ratio **`string` + +> Seedance 2.0 & 2.0 fast 默认值： adaptive + +生成视频的宽高比例。不同宽高比对应的宽高像素值见下方表格。 + +* 16:9 + +* 4:3 + +* 1:1 + +* 3:4 + +* 9:16 + +* 21:9 + +* adaptive：根据输入自动选择最合适的宽高比 + +> **adaptive 适配规则** +> +> 当配置 **ratio** 为 adaptive 时，模型会根据生成场景自动适配宽高比；实际生成的视频宽高比可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **ratio** 字段获取。 +> +> * 文生视频：根据输入的提示词，智能选择最合适的宽高比。 +> +> * 首帧 / 首尾帧生视频：根据上传的首帧图片比例，自动选择最接近的宽高比。 +> +> * 多模态参考生视频：根据用户提示词意图判断，如果是首帧生视频/编辑视频/延长视频，以该图片/视频为准选择最接近的宽高比；否则，以传入的第一个媒体文件为准（优先级：视频＞图片）选择最接近的宽高比。 + +*** + +**不同宽高比对应的宽高像素值：** + +| 分辨率 | 宽高比 | 宽高像素值 | +| ---- | ---- | -------- | +| 480p | 16:9 | 864×496 | +| | 4:3 | 752×560 | +| | 1:1 | 640×640 | +| | 3:4 | 560×752 | +| | 9:16 | 496×864 | +| | 21:9 | 992×432 | +| 720p | 16:9 | 1280×720 | +| | 4:3 | 1112×834 | +| | 1:1 | 960×960 | +| | 3:4 | 834×1112 | +| | 9:16 | 720×1280 | +| | 21:9 | 1470×630 | + + + +#### **duration** `integer` + +> Seedance 2.0 & 2.0 fast 默认值：5 + +生成视频时长，仅支持整数，单位：秒。 + +取值范围： + +* \[4,15] 或设置为-1 + +> **配置方法** +> +> * 指定具体时长：支持有效范围内的任一整数。 +> +> * 智能指定：设置为 -1，表示由模型在有效范围内自主选择合适的视频长度（整数秒）。实际生成视频的时长可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **duration** 字段获取。注意视频时长与计费相关，请谨慎设置。 + + + +#### **frames** `integer` + +Seedance 2.0 & 2.0 fast 暂不支持 + + + +#### **camera\_fixed** `boolean` + + Seedance 2.0 & 2.0 fast 暂不支持 + + + +# Get/List-查询视频生成任务/列表 + +> [查询视频生成任务](https://www.volcengine.com/docs/82379/1521309?lang=zh)：GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{id} +> +> [查询视频生成任务列表](https://www.volcengine.com/docs/82379/1521675?lang=zh)：GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?page\_num={page\_num}\&page\_size={page\_size}\&filter.status={filter.status}\&filter.task\_ids={filter.task\_ids}\&filter.model={filter.model} + +## 响应参数 + +#### **tools **`object[]` + +> 仅 Seedance 2.0 & 2.0 fast 支持 + +配置模型要调用的工具。 + +*** + +tools.**type **`string` + +指定使用的工具类型。 + +* web\_search：联网搜索工具。 + + + +#### **usage** `object` + +本次请求的 token 用量。 + +*** + +usage.**completion\_tokens** `integer` + +模型输出视频花费的 token 数量。 + +*** + +usage.**total\_tokens** `integer` + +本次请求消耗的总 token 数量。 + +*** + +usage.**tool\_usage **`object` + +> 仅 Seedance 2.0 & 2.0 fast 支持 + +使用工具的用量信息。 + +*** + +usage.tool\_usage.**web\_search **`integer` + +实际调用联网搜索工具的次数，仅开启联网搜索时返回。 + + + +# 调用简介及示例 + +## 流程简介 + +任务接口是异步接口，视频生成任务流程 + +1. 创建视频生成任务接口创建视频生成任务 + +2. 定时使用查询接口查询视频生成任务状态 + + 1. 任务 running，过段时间再查询任务状态 + + 2. 任务完成，返回视频链接，在24小时内下载生成的视频文件 + +## 1. 创建视频生成任务 + +> 以下示例仅展示 Seedance 2.0 & 2.0 fast 新增能力，更多视频生成示例详见 [创建视频生成任务 API](https://www.volcengine.com/docs/82379/1520757)。 + +### 多模态参考 + +```bash +curl https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ARK_API_KEY" \ + -d '{ + "model": "doubao-seedance-2-0-260128", + "content": [ + { + "type": "text", + "text": "全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。第一人称视角果茶宣传广告，seedance牌「苹苹安安」苹果果茶限定款；首帧为图片1，你的手摘下一颗带晨露的阿克苏红苹果，轻脆的苹果碰撞声；2-4 秒：快速切镜，你的手将苹果块投入雪克杯，加入冰块与茶底，用力摇晃，冰块碰撞声与摇晃声卡点轻快鼓点，背景音：「鲜切现摇」；4-6 秒：第一人称成品特写，分层果茶倒入透明杯，你的手轻挤奶盖在顶部铺展，在杯身贴上粉红包标，镜头拉近看奶盖与果茶的分层纹理；6-8 秒：第一人称手持举杯，你将图片2中的果茶举到镜头前（模拟递到观众面前的视角），杯身标签清晰可见，背景音「来一口鲜爽」，尾帧定格为图片2。背景声音统一为女生音色。" + }, + { + "type": "image_url", + "image_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg" + }, + "role": "reference_image" + }, + { + "type": "image_url", + "image_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg" + }, + "role": "reference_image" + }, + { + "type": "video_url", + "video_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4" + }, + "role": "reference_video" + }, + { + "type": "audio_url", + "audio_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3" + }, + "role": "reference_audio" + } + ], + "generate_audio":true, + "ratio": "16:9", + "duration": 11, + "watermark": false +}' +``` + +### 编辑视频 + +```bash +curl https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ARK_API_KEY" \ + -d '{ + "model": "doubao-seedance-2-0-260128", + "content": [ + { + "type": "text", + "text": "将视频1礼盒中的香水替换成图片1中的面霜，运镜不变" + }, + { + "type": "image_url", + "image_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_edit_pic1.jpg" + }, + "role": "reference_image" + }, + { + "type": "video_url", + "video_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_edit_video1.mp4" + }, + "role": "reference_video" + } + ], + "generate_audio": true, + "ratio": "16:9", + "duration": 5, + "watermark": true +}' +``` + +### 延长视频 + +```bash +curl https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ARK_API_KEY" \ + -d '{ + "model": "doubao-seedance-2-0-260128", + "content": [ + { + "type": "text", + "text": "视频1中的拱形窗户打开，进入美术馆室内，接视频2，之后镜头进入画内，接视频3" + }, + { + "type": "video_url", + "video_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video1.mp4" + }, + "role": "reference_video" + }, + { + "type": "video_url", + "video_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video2.mp4" + }, + "role": "reference_video" + }, + { + "type": "video_url", + "video_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video3.mp4" + }, + "role": "reference_video" + } + ], + "generate_audio": true, + "ratio": "16:9", + "duration": 8, + "watermark": true +}' +``` + +### 使用联网搜索 + +仅支持文本生视频 + +```bash +curl https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ARK_API_KEY" \ + -d '{ + "model": "doubao-seedance-2-0-260128", + "content": [ + { + "type": "text", + "text": "微距镜头对准叶片上翠绿的玻璃蛙。焦点逐渐从它光滑的皮肤，转移到它完全透明的腹部，一颗鲜红的心脏正在有力地、规律地收缩扩张。" + } + ], + "generate_audio":true, + "ratio": "16:9", + "duration": 11, + "watermark": true, + "tools": [ + { + "type": "web_search" + } + ] +}' +``` + +## 2. 查询视频生成任务 + +```bash +//请将 cgt-2026****hzc2z 替换为创建视频生成任务时获得的任务ID +curl -X GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/cgt-2026****hzc2z \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ARK_API_KEY" +``` + + + +# 最佳实践 + +## 使用公共虚拟人像生成视频 + +平台提供公共虚拟人像素材库，目前您可以使用其中的图像素材来创建一个统一、完备的视频主角。帮助您更好地控制主角，并确保其形象在多段视频中保持一致，避免因为真人人脸限制导致角色无法统一的问题。 + +素材模态目前包含图片，并提供人物背景描述。每个素材对应一个独立素材 ID (asset ID)，在体验中心的视频生成任务中，指定角色人脸生成视频。 + +1. 在浏览器中打开[体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)，点击输入框下方的 **虚拟人像库** 页签。 + +2. 检索需要使用的人像，支持使用自然语言检索及筛选框组合筛选。 + +| 输入：文本 | 输入：虚拟人像、图片 | 输出 | +| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | +| **图片1**中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持**图片2**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 | ![Image Token: HTf6bPRukoWaW4xnCSlcvKtUn7c](images/HTf6bPRukoWaW4xnCSlcvKtUn7c.png)![Image Token: YfCDbzJlqo4yzZxCmdscWdsInCf](images/YfCDbzJlqo4yzZxCmdscWdsInCf.jpeg) | | + + + +在 [Video Generation API](https://www.volcengine.com/docs/82379/1520758) 的 **content.<模态>\_url.url** 字段中使用 素材 URI 生成视频。 + +> 输入的参考内容，包括人像素材，需符合视频生成限制，具体信息请查看使用限制。 +> +> **注意**： +> +> * 首次在 API 中使用虚拟人像素材 Asset URI 前，需先在[方舟体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)提交一次视频生成任务，阅读并同意弹出的 **虚拟人像库使用协议**。 +> +> * 体验中心支持体验视频生成能力。默认单次生成 4 段视频，为节约成本，建议设置为每次生成 1 条，具体方式可参考[虚拟人像库](https://www.volcengine.com/docs/82379/2223965?lang=zh)。 + +同意协议的操作方式如下： + +![Image Token: LK8ybUN9Ko2KkQxq2FdclVQtnkh](images/LK8ybUN9Ko2KkQxq2FdclVQtnkh.gif) + +示例代码： + +> **注意：** +> 在传入给模型的 Prompt 中，需要使用**图片 1**、**视频 1 **的方式指代参考素材，素材序号为素材在请求体中的顺序。请勿直接在 Prompt 中直接使用 Asset ID。 +> 例：“**图片1 **里的女孩身着**图片2**中的服装，正在整理柜台上的物品。**图片3**中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。” +> +> 调用示例请参考[常见问题 4](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-YOKvdYHjro8EjtxucWaczf6vneg) + +```python +import os +import time +# Install SDK: pip install 'volcengine-python-sdk[ark]' +from volcenginesdkarkruntime import Ark +client = Ark( + # The base URL for model invocation + base_url='https://ark.cn-beijing.volces.com/api/v3', + # Get API Key：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey + api_key=os.environ.get("ARK_API_KEY"), +) +if __name__ == "__main__": + print("----- create request -----") + create_result = client.content_generation.tasks.create( + model="doubao-seedance-2-0-260128", # Replace with Model ID + content=[ + { + "type": "text", + # 注意：素材图片指代需使用“图片N”（ N 表示传入素材图片/图片的序号，如“图片1”、“图片2”） + "text": "图片1中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持图片2的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。" + }, + { + "type": "image_url", + "image_url": { + "url": "asset://asset-20260224200602-qn7wr" + }, + "role": "reference_image" + }, + { + "type": "image_url", + "image_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_edit_pic1.jpg" + }, + "role": "reference_image" + }, + ], + generate_audio=True, + ratio="16:9", + duration=11, + watermark=True, + ) + print(create_result) + print("----- polling task status -----") + task_id = create_result.id + while True: + get_result = client.content_generation.tasks.get(task_id=task_id) + status = get_result.status + if status == "succeeded": + print("----- task succeeded -----") + print(get_result) + break + elif status == "failed": + print("----- task failed -----") + print(f"Error: {get_result.error}") + break + else: + print(f"Current status: {status}, Retrying after 30 seconds...") + time.sleep(30) +``` + +*** + +## 使用自有虚拟人像素材生成视频 + +Seedance 2.0 及 2.0 fast 模型具有完备的防范 Deepfake 和侵犯版权风险能力。在生成视频时，会对有风险的参考素材输入进行拦截，最大限度保证生成视频合规和安全性。 + +为确保创作者能充分利用 Seedance 2.0 系列模型强大的视频生成能力高效生成视频内容，同时规避 AI 生成内容的潜在风险，方舟推出了私域可信素材库，支持创作者自助上传虚拟人像素材。完成入库的可信素材将进入您的私域素材库，在视频生成中使用。 + +> 具体信息请参考文档：[ 「⚠️保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)。 + +*** + +## 使用模型产物进行二创 + +Seedance 2.0 及 2.0 fast 模型生成的视频为受信素材。您可使用**本账号下**由上述模型生成的视频，进行视频编辑、视频延长等二次创作，素材中的人脸可正常参与生成，不会触发审核拦截。 + +> 2026年3月11日起，使用 Seedance 2.0 及 2.0 fast 模型生成的视频，支持二次创作。 + +| 输入：文本 | 输入：虚拟人像、图片 | 第一次输出视频 | 二次编辑后视频 | +| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | +| **图片1**中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持**图片2**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 | ![Image Token: MbrRbjSSDoqaaKx3YmCcbVZUnud](images/MbrRbjSSDoqaaKx3YmCcbVZUnud.png)![Image Token: UGfibSj7soIYJMxoYpEcDBIcnkb](images/UGfibSj7soIYJMxoYpEcDBIcnkb.jpeg) | | | + +1. 首次生视频，并获取视频 URL。 + +> **注意：** +> 在传入给模型的 Prompt 中，需要使用**图片 1**、**视频 1 **的方式指代参考素材，素材序号为素材在请求体中的顺序。 +> +> 请勿直接在 Prompt 中直接使用 Asset ID。 +> 例：“**图片1 **里的女孩身着**图片2**中的服装，正在整理柜台上的物品。**图片3**中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。” + +```python +import os +import time +# Install SDK: pip install 'volcengine-python-sdk[ark]' +from volcenginesdkarkruntime import Ark +client = Ark( + # The base URL for model invocation + base_url='https://ark.cn-beijing.volces.com/api/v3', + # Get API Key：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey + api_key=os.environ.get("ARK_API_KEY"), +) +if __name__ == "__main__": + print("----- create request -----") + create_result = client.content_generation.tasks.create( + model="doubao-seedance-2-0-260128", # Replace with Model ID + content=[ + { + "type": "text", + # 注意：素材图片指代需使用“图片N”（ N 表示传入素材图片/图片的序号，如“图片1”、“图片2”） + "text": "图片1中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持图片2的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。" + }, + { + "type": "image_url", + "image_url": { + "url": "asset://asset-20260224200602-qn7wr" + }, + "role": "reference_image" + }, + { + "type": "image_url", + "image_url": { + "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_edit_pic1.jpg" + }, + "role": "reference_image" + }, + ], + generate_audio=True, + ratio="16:9", + duration=11, + watermark=True, + ) + print(create_result) + print("----- polling task status -----") + task_id = create_result.id + while True: + get_result = client.content_generation.tasks.get(task_id=task_id) + status = get_result.status + if status == "succeeded": + print("----- task succeeded -----") + print(get_result) + break + elif status == "failed": + print("----- task failed -----") + print(f"Error: {get_result.error}") + break + else: + print(f"Current status: {status}, Retrying after 30 seconds...") + time.sleep(30) +``` + +* 对首次生成的视频进行再次编辑。为直观展示效果，本示例中直接使用视频原始 URL。 + +> 视频原始 URL 的有效期仅 24 小时，实际使用时，建议您提前转存视频文件（例如上传至火山引擎TOS）。 + +```python +import os +import time +# Install SDK: pip install 'volcengine-python-sdk[ark]' +from volcenginesdkarkruntime import Ark +client = Ark( + # The base URL for model invocation + base_url='https://ark.cn-beijing.volces.com/api/v3', + # Get API Key：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey + api_key=os.environ.get("ARK_API_KEY"), +) +if __name__ == "__main__": + print("----- create request -----") + create_result = client.content_generation.tasks.create( + model="doubao-seedance-2-0-260128", # Replace with Model ID + content=[ + { + "type": "text", + "text": "将视频1中的背景修改为室内，房间布置温馨，包括白色的沙发，梳妆台和鲜花。" + }, + { + "type": "video_url", + "video_url": { + "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedance-2-0/02177390693606300000000000000000000ffffc0a88a7fb18e5d.mp4?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTMjQyZTA4MzFjYTY0NGE5YzgzNTIzMTQzYWI5MmVjMDY%2F20260319%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260319T075900Z&X-Tos-Expires=86400&X-Tos-Signature=204c1d922d7f563ab0fe2bdf28fe3764df52b3404827acf11c9f3dead82aa3db&X-Tos-SignedHeaders=host" + }, + "role": "reference_video" + }, + ], + generate_audio=True, + ratio="16:9", + duration=11, + watermark=True, + ) + print(create_result) + print("----- polling task status -----") + task_id = create_result.id + while True: + get_result = client.content_generation.tasks.get(task_id=task_id) + status = get_result.status + if status == "succeeded": + print("----- task succeeded -----") + print(get_result) + break + elif status == "failed": + print("----- task failed -----") + print(f"Error: {get_result.error}") + break + else: + print(f"Current status: {status}, Retrying after 30 seconds...") + time.sleep(30) +``` + + + +## 私域素材资产上传最佳案例 + +> 在上传素材资产时，**若将目标人脸图、全身参考图及细节参考图合并为同一张图片，可能导致各参考元素在画面中占比较小，从而增加模型识别难度**，造成生成视频中的人物形象与所上传素材资产出现偏差，或造成生成视频中素人脸被误识别为明星脸而触发风控拦截。 + +建议在上传素材资产时，将人物面部特写、服装细节等关键内容独立分割为单独的图片进行上传。具体可参考如下规则及示例： + +| | 应该 | 不应该 | | +| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词![图片1-背景参考图 (Token: Hi55bqOYyoBWvSxMDjNcEuSJn7c)](images/Hi55bqOYyoBWvSxMDjNcEuSJn7c.png)![图片2-人物妆造三视图 (Token: XQE5bI0tJovdxmxf0qMcFCtEnoc)](images/XQE5bI0tJovdxmxf0qMcFCtEnoc.png)![图片3-人物面部特写图 (Token: BpkhbHY0Co0pB0xTgoRcLDOynGc)](images/BpkhbHY0Co0pB0xTgoRcLDOynGc.png) | 给出背景参考图、人物妆造三视图、提示词![图片1-背景参考图 (Token: T572bL5IGooP4HxogzGcwERRn5c)](images/T572bL5IGooP4HxogzGcwERRn5c.png)![图片2-人物妆造三视图 (Token: WZIcbGijXoOOZnxQRS9cA4kMndh)](images/WZIcbGijXoOOZnxQRS9cA4kMndh.png) | | +| 输出内容 | | | | +| 总结 | 同样是古风打斗剧情：左边输入内容包括：背景参考图、**人物妆造三视图**、**人物面部无表情特写图**、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正视图、提示词。左边的输出视频更加还原人物面部特征；右边的人物面部特征一致性遵循不佳。 | | | +| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词![图片1-背景参考图 (Token: JLD7bmUBYo7FpaxiAsicLkMQnKe)](images/JLD7bmUBYo7FpaxiAsicLkMQnKe.jpeg)![图片2-人物妆造三视图 (Token: Xj45b0L5uopyMqxTUOLcwn0ZnCc)](images/Xj45b0L5uopyMqxTUOLcwn0ZnCc.jpeg)![图片3-人物面部特写图 (Token: S7JRbu09Jo9OdkxHy7TcWTarnRh)](images/S7JRbu09Jo9OdkxHy7TcWTarnRh.png)![图片4-人物妆造三视图 (Token: KS5hb2DlCoLL6uxHnfdcl9konBe)](images/KS5hb2DlCoLL6uxHnfdcl9konBe.jpeg)![图片5-人物面部特写图 (Token: NtOnbySAHokJ4JxR4sdcu8oRnyh)](images/NtOnbySAHokJ4JxR4sdcu8oRnyh.jpeg) | 给出背景参考图、人物妆造三视图、提示词![图片1-背景参考图 (Token: I3ICbosi0oaR1LxcezKcYJWCnic)](images/I3ICbosi0oaR1LxcezKcYJWCnic.jpeg)![图片2-人物妆造三视图 (Token: JtOLbQ1iLoxTPUxXrkLcMcXknB8)](images/JtOLbQ1iLoxTPUxXrkLcMcXknB8.jpeg)![图片3-人物妆造三视图 (Token: RGoubMdjTokEK3xjJ3KcQqPtnuf)](images/RGoubMdjTokEK3xjJ3KcQqPtnuf.jpeg) | 给出背景参考图、人物妆造正视图、提示词![图片1-背景参考图 (Token: YCcmbhQVFoUcHcxExHfcSrSQnab)](images/YCcmbhQVFoUcHcxExHfcSrSQnab.jpeg)![图片2-人物妆造正视图 (Token: OoMFbcfBEoiqkCxOQJpcjgcAnzQ)](images/OoMFbcfBEoiqkCxOQJpcjgcAnzQ.png)![图片3-人物妆造正视图 (Token: ZAs6bIUkQooRUBxxe2EcHDQ2nug)](images/ZAs6bIUkQooRUBxxe2EcHDQ2nug.png) | +| 输出内容 | | | | +| 总结 | 同样是温馨亲子剧情：左边输入内容包括：背景参考图、**人物妆造三视图、人物面部无表情特写图**、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正面图、提示词。左边的输出视频更加还原人物面部特征；中间的输出视频人物面部特征一致性遵循不佳；右边人物妆造、面部特征一致性遵循不佳。 | | | + + + diff --git a/docs/API文档/3-31「保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）.md b/docs/API文档/3-31「保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）.md new file mode 100644 index 0000000..ee890ae --- /dev/null +++ b/docs/API文档/3-31「保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）.md @@ -0,0 +1,1005 @@ +# 「⚠️保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版） + +| **文档变更说明** | **时间** | +| ---------- | --------- | +| | 2026.3.26 | +| | 2026.3.28 | + +本文介绍素材资产（Assets）API 接口的参数。您可以使用以下 Assets API 接口创建、管理个人人像素材资产。 + +> 本文档仅限预览及邀测用户使用： +> +> * 不承诺正式 API 上线100%一致。 +> +> * 仅限邀测用户阅读，请勿截图/分享给其他人员。 +> +> * 上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。 +> +> * 素材资产应为虚拟人像，非虚拟人像类素材无需入库。 +> +> * 您需确保上传的虚拟人像符合以下条件： +> +> * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。 +> +> * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。 +> +> * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。 + + + +# 素材资产库结构说明 + +* **Asset Group（素材资产组合）**：单个素材文件为一个 Asset，每个 Asset 属于一个 Asset Group。 + + * 可以使用素材组自由管理素材，例如可将同一虚拟人物素材放入同一素材组合进行管理。 + +* **Asset（素材资产）**：一个素材文件（当前支持上传图像、视频、音频），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。 + +> 注意 +> +> * 仅需入库推理需使用的素材资产，不需使用的素材资产请勿入库。 +> +> * 仅可使用已入库素材资产的 Id (Asset ID) 进行视频生成，同一形象未入库素材无法使用。 +> +> * 每个上传的素材资产需经过预处理，可轮询调用 **GetAsset** 接口查询素材状态（对应参数为 **Status）**，仅当状态变为 `Active` 后，该素材资产方可用于后续推理使用；若状态为 `Failed` 则表示处理失败，无法用于后续推理使用。**详情可参考：[上传素材资产并获取素材资产信息代码示例](https://bytedance.larkoffice.com/wiki/FtqVwjinYisraGkT5uncWyd0nEb#share-U55kdtSMVowUy9xkpJBcEazonpe)。** + + + +# 素材资产（Assets）API 接口功能 + +## **Asset (Group) 创建接口：** + +1. CreateAssetGroup：创建素材资产组合。**首次创建素材资产组合时需在控制台签署授权函，详情参考 [ 私域虚拟人像素材库 (WIP)](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)** + +2. CreateAsset：创建素材资产。该接口可用于上传个人素材资产，创建素材资产后可利用返回字段中的素材 **Id （需处于 `Active` 状态）**用于 Seedance 2.0 系列模型生成视频。 + + + +## **Asset (Group) 管理接口：** + +* ListAssetGroups：查询素材资产组合列表。 + +* ListAssets：查询素材资产列表。 + +* GetAsset：查询素材资产信息。 + +* GetAssetGroup：查询素材资产组合信息。 + +* UpdateAssetGroup：更新素材资产组合信息。 + +* UpdateAsset：更新素材资产信息。 + +* DeleteAsset：删除单个素材资产。 + + + +# 鉴权方式 + +调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [获取 API 访问密钥（AK/SK）](https://www.volcengine.com/docs/6257/64983?lang=zh)。 + + + +# 限流要求 + +* QPS 限流： API接口每秒查询请求的总数上限。超过此限制的查询请求会报错。 + +| 接口名 | 账号维度的 QPS 限流 | +| ---------------- | ------------ | +| CreateAssetGroup | 30 | +| CreateAsset | 1 | +| ListAssetGroups | 30 | +| ListAssets | 30 | +| GetAsset | 100 | +| GetAssetGroup | 100 | +| UpdateAsset | 30 | +| UpdateAssetGroup | 30 | + +# CreateAssetGroup + +> **POST **/open/CreateAssetGroup + +创建 Asset Group（素材资产组合）组合，用作素材资产管理。 + +> **首次创建 Asset Group（素材资产组合）需在控制台签署授权函，详情参考 [ 私域虚拟人像素材库 (WIP)](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)** + +## 请求参数 + +### **Name** `string` `必填` + +Asset Group（素材资产组合）的名称，上限为 64 字符。 + +*** + +### **Description** `string` + +Asset Group（素材资产组合）的描述，上限为 300 字符。 + +*** + +### **GroupType **`string` + +Asset Group（素材资产组合）的类型。可选值： + +* AIGC：虚拟人像。 + +> 当前仅支持 AIGC 类型。 + + + +*** + +### **ProjectName **`string`** ** + +资源所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id** `string` + +Asset Group（素材资产组合）的 Id。 + +*** + +返回示例： + + + +# CreateAsset + +> **POST **/open/CreateAsset + +向指定的Asset Group（素材资产组合）内创建Asset（素材资产）。 + +> 上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。 + +## 请求参数 + +### **GroupId** `string` `必填` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +### **URL** `string` `必填` + +传入的Asset（素材资产）的公共可访问地址。 + +*** + +### **Name** `string` + +Asset（素材资产）的名称，上限为64个字符。 + +> 该字段仅用于使用 ListAssets 接口时模糊搜索素材，不会被带入模型推理。关于如何使用素材生成视频，请参考[使用人像素材生成视频](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-QF2qdZE5HoRkRDxfs9bcmqECnDb)和[常见问题 4](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-YOKvdYHjro8EjtxucWaczf6vneg)。 + +*** + +### **AssetType `string` `必填`** + +Asset（素材资产）的类型，支持传入图像、音频、视频。可选值： + +* Image：Asset（素材资产）的类型为图像。 + +* Video：Asset（素材资产）的类型为视频。 + +* Audio：Asset（素材资产）的类型为音频。 + +> **传入图像、音频、视频素材时，仅支持上传 URL ，不支持 base64。** +> +> **传入单个图像要求** +> +> * 格式：jpeg、png、webp、bmp、tiff、gif、heic/heif +> +> * 宽高比（宽/高）： (0.4, 2.5) +> +> * 宽高长度（px）：(300, 6000) +> +> * 大小：单张图片小于 30 MB +> +> **传入单个视频要求** +> +> * 格式：mp4、mov +> +> * 分辨率：480p、720p +> +> * 时长：单个视频时长 \[2, 15] s +> +> * 尺寸： +> +> * 宽高比（宽/高）：\[0.4, 2.5] +> +> * 宽高长度（px）：\[300, 6000] +> +> * 总像素数：\[640×640=409600, 834×1112=927408]，即宽和高的乘积符合 \[409600, 927408] 的区间要求。 +> +> * 大小：单个视频不超过 50 MB +> +> * 帧率 (FPS)：\[24, 60] +> +> **传入单个音频要求** +> +> * 格式：wav、mp3 +> +> * 时长：单个音频时长 \[2, 15] s +> +> * 大小：单个音频不超过 15 MB + +*** + +### **ProjectName** `string` + +资源所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +> 需要和待传入的 Asset Group（素材资产组合）的 **ProjectName **保持一致。 + +*** + + + +## 返回参数 + +### **Id **`string` + +Asset（素材资产）的 Id。 + +*** + +返回示例： + + + +# ListAssets + +> **POST **/open/ListAssets + +查询符合筛选条件的 Assets（素材资产）列表。 + +## 请求参数 + +### **Filter** `object` `必填` + +搜索的过滤条件。 + +*** + +Filter.**GroupIds** `array` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +Filter.**GroupType** `string` `必填` + +Asset Group（素材资产组合）的类型。可选值： + +* AIGC：虚拟人像。 + +*** + +Filter.**Statuses** `array`** ** + +任务状态。 + +* Active：素材资产（Asset）已处理完毕，可以使用。 + +* Processing：素材资产（Asset）正在预处理，无法使用。 + +* Failed：素材资产（Asset）处理失败。 + +*** + +Filter.**Name** `string`** ** + +Asset（素材资产）的名称，上限为64个字符。 + +*** + +### **PageNumber** `int (i64)` `必填` + +搜索页码，可用于列表分页功能，从 1 开始。例如："page\_number": 1，即返回第一页的搜索结果。 + +*** + +### **PageSize** `int (i64)` `必填` + +每页搜索结果的数量，上限为100。 + +*** + +### **SortBy** `string` + +用于排序的字段名称，默认值 `createTime`。支持以下类型： + +* CreateTime：根据创建时间排序。 + +* UpdateTime：根据更新时间排序。 + +* GroupId：根据资产素材组的 Id 排序。 + +*** + +### **SortOrder** `string` + +排序顺序，默认值 `Desc`。可选值： + +* Desc：降序 + +* Asc：升序 + +*** + +### **ProjectName** `string` + +资源所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Items** `array[]` + +符合筛选条件的Asset（素材资产）数组。 + +*** + +Items.**Id** `string` + +Asset（素材资产）的 Id。 + +*** + +Items.**name** `string` + +Asset（素材资产）的名称，上限为64个字符。 + +*** + +Items.**URL** `string` + +Asset（素材资产）的公共可访问地址。有效期为12小时，请及时保存。 + +*** + +Items.**GroupId** `string` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +Items.**AssetType** `string` + +Asset（素材资产）的类型，支持传入图像、音频、视频。支持类型： + +* Image：Asset（素材资产）的类型为图像。 + +* Video：Asset（素材资产）的类型为视频。 + +* Audio：Asset（素材资产）的类型为音频。 + +*** + +Items.**Status** `string` + +任务状态。 + +* Active：素材资产（Asset）已处理完毕，可以使用。 + +* Processing：素材资产（Asset）正在预处理，无法使用。 + +* Failed：素材资产（Asset）处理失败。 + +*** + +Items.**Error** `object` + +错误信息。 + +*** + +Items.Error.**Code** `string` + +错误码。 + +*** + +Items.Error.**Message** `string` + +错误信息。 + +*** + +Items.**ProjectName** `string` + +资源所属的项目名称。 + +*** + +Items.**CreateTime **`string` + +创建时间。 + +*** + +Items.**UpdateTime **`string` + +更新时间。 + +*** + +### **TotalCount **`int (i64)` + +返回总数。 + +*** + +### **PageNumber **`int (i64)` + +返回的页数。 + +*** + +### **PageSize **`int (i64)` + +每页搜索结果的数量，上限为100。 + + + +# ListAssetGroups + +> **POST **/open/ListAssetGroups + +查询符合筛选条件的Asset Groups（素材资产组合）列表。 + +## 请求参数 + +### **Filter** `object` `必填` + +搜索的过滤条件。 + +*** + +Filter.**name** `string` + +Asset Group（素材资产组合）的名称，上限为64个字符。 + +*** + +Filter.**GroupIds** `array` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +Filter.**GroupType** `string`** **`必填` + +Asset Group（素材资产组合）的类型。可选值： + +* AIGC：虚拟人像。 + +*** + +### **PageNumber** `int (i64)` + +搜索页码，可用于列表分页功能，从 1 开始。例如："page\_number": 1，即返回第一页的搜索结果。 + +*** + +### **PageSize** `int (i64)` + +每页搜索结果的数量，上限为100。 + +*** + +### **SortBy** `string` + +用于排序的字段名称，默认值 `createTime`。支持以下类型： + +* CreateTime：根据创建时间排序。 + +* UpdateTime：根据更新时间排序。 + +*** + +### **SortOrder** `string` + +排序顺序，默认值 `Desc`。可选值： + +* Desc：降序 + +* Asc：升序 + +*** + +### **ProjectName** `string` + +资源所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **TotalCount **`int (i64)` + +返回的 Asset Group（素材资产组合）的总数。 + +*** + +### **Items** `array[]` + +符合筛选条件的 Asset Group（素材资产组合）数组。 + +*** + +Items.**Id** `string` + +Asset Group（素材资产组合）的 Id。 + +*** + +Items.**Name** `string` + +Asset Group（素材资产组合）的名称，上限为64个字符。 + +*** + +Items.**Title** `string` + +Asset Group（素材资产组合）的标题。 + +> 已废弃，请直接使用参数 Name + +*** + +Items.**Description** `string` + +Asset Group（素材资产组合）的描述，上限为 300 字符。 + +*** + +Items.**GroupType** `string` + +Asset Group（素材资产组合）的类型。 + +* AIGC：虚拟人像。 + +*** + +Items.**ProjectName** `string` + +资源所属的项目名称。 + +*** + +Items.**CreateTime** `string` + +创建时间。 + +*** + +Items.**UpdateTime** `string` + +更新时间。 + +*** + +### **PageNumber **`int (i64)` + +返回的页数。 + +*** + +### **PageSize **`int (i64)` + +每页搜索结果的数量，上限为100。 + +*** + + + +# GetAssetGroup + +> **POST **/open/GetAssetGroup + +获取单个Asset Group（素材资产组合）信息。 + +## 请求参数 + + + +### **Id **`string` `必填` + +Asset Group（素材资产组合）的 Id + +*** + +### **ProjectName **`string` + +需要查询的 Asset Group（素材资产组合）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id** `string` + +Asset Group（素材资产组合）的 Id。 + +*** + +### **Name** `string` + +Asset Group（素材资产组合）的名称，上限为64个字符。 + +*** + +### **Title** `string` + +Asset Group（素材资产组合）的标题。 + +> 已废弃，请直接使用参数 Name + +*** + +### **Description** `string` + +Asset Group（素材资产组合）的描述，上限为 300 字符。 + +*** + +### **GroupType **`string` + +Asset Group（素材资产组合）的类型。 + +* AIGC：虚拟人像 + +*** + +### **ProjectName **`string`** ** + +资源所属的项目名称。 + +*** + +### **CreateTime **`string` + +创建时间。 + +*** + +### **UpdateTime **`string` + +更新时间。 + +*** + +## + +# GetAsset + +> **POST **/open/GetAsset + +获取单个Asset（素材资产）信息。 + +## 请求参数 + + + +### **Id **`string` `必填` + +Asset（素材资产）的 Id。 + +*** + +### **ProjectName **`string` + +需要查询的 Asset（素材资产）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id **`string` + +Asset（素材资产）的 Id。 + +*** + +### **Name** `string` + +Asset（素材资产）的名称，上限为64个字符。 + +*** + +### **URL **`string` + +Asset（素材资产）的访问地址。有效期为12小时，请及时保存。 + +*** + +### **AssetType **`string` + +Asset（素材资产）的类型，支持传入图像、音频、视频。支持类型： + +* Image：Asset（素材资产）的类型为图像。 + +* Video：Asset（素材资产）的类型为视频。 + +* Audio：Asset（素材资产）的类型为音频。 + +*** + +### **GroupId** `string` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +### **Status** `string` + +任务状态。 + +* Active：素材资产（Asset）已处理完毕，可以使用。 + +* Processing：素材资产（Asset）正在预处理，无法使用。 + +* Failed：素材资产（Asset）处理失败。 + +*** + +### **Error** `object` + +错误信息。 + +*** + +Error.**Code** `string` + +错误码。 + +*** + +Error.**Message** `string` + +错误信息。 + +*** + +### **CreateTime **`string` + +创建时间。 + +*** + +### **UpdateTime ** `string` + +更新时间。 + +*** + +### **ProjectName** `string` + +资源所属的项目名称。 + +*** + +## + +# **UpdateAssetGroup** + +> **POST **/open/UpdateAssetGroup + +更新单个 Asset Group（素材资产组合）信息。当前仅支持更新 Asset Group（素材资产组合）的 Name 和 Description。 + +## 请求参数 + +### **Id **`string` `必填` + +需要更新的 Asset Group（素材资产组合）的 Id。 + +*** + +### **Name **`string` + +需要更新的 Asset Group（素材资产组合）的新名称，上限为64个字符。 + +*** + +### **Description** `string` + +需要更新的 Asset Group（素材资产组合）的新描述，上限为 300 字符。 + +*** + +### **ProjectName** `string` + +需要更新的 Asset Group（素材资产组合）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id** `string` + +Asset Group（素材资产组合）的 Id。 + +*** + + + + + +# **UpdateAsset** + +> **POST **/open/UpdateAsset + +更新单个Asset（素材资产）信息。当前仅支持更新Asset（素材资产）的 Name。 + +## 请求参数 + +### **Id **`string` `必填` + +需要更新的 Asset（素材资产）的 Id。 + +*** + +### **Name **`string` + +需要更新的 Asset（素材资产）的新名称，上限为64个字符。 + +*** + +### **ProjectName** `string` + +需要更新的 Asset（素材资产）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id** `string` + +Asset（素材资产）的 Id。 + +*** + + + +# **DeleteAsset** + +> **POST **/open/DeleteAsset + +删除单个 Asset（素材资产）。 + +## 请求参数 + +### **Id **`string` `必填` + +需要删除的 Asset（素材资产）的 Id。 + +*** + +### **ProjectName** `string` + +需要删除的 Asset（素材资产）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +本接口无返回参数。 + +*** + + + +# 代码示例： + +> **以下示例为使用 Asset API 创建素材资产并用于视频生成的使用链路：** +> +> 1. **创建素材资产组合：**调用 **CreateAssetGroup** 接口创建一个素材资产组合（Asset Group），用于对同一项目或人物的素材进行统一管理。首次创建时需在控制台签署授权函。 +> +> 2. **上传素材资产并等待预处理完成：**调用 **CreateAsset** 接口上传图片/视频/音频素材，传入素材的公共访问URL及所属的Group ID，获得素材资产ID（Asset ID）。 +> 由于上传的素材资产需经过预处理后才能使用，可轮询调用 **GetAsset** 接口查询素材状态，直至状态变为 `Active`。若状态为 `Failed` 则表示处理失败，无法用于后续推理使用。 +> +> 3. **在视频生成 API 中使用素材：**当素材资产状态为 `Active` 后，将素材ID按 `asset://`** 的格式拼接成URL，在视频生成API（如Seedance 2.0系列模型）的请求中，将该URL作为参考图片/视频/音频的 `image_url` 传入，即可使用该素材资产生成视频。 +> +> **API 鉴权方式区别说明** +> +> * **Asset API：**Access Key 鉴权，详情参考 [获取 API 访问密钥（AK/SK）](https://www.volcengine.com/docs/6257/64983?lang=zh)。 +> +> * **视频生成 API：**API Key 鉴权，详情参考 [管理 API Key](https://www.volcengine.com/docs/82379/1361424?lang=zh)。 +> +> **素材库[项目](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)（Project）隔离说明** +> +> * 向指定的 Asset Group（素材资产组合）内创建或查询 Asset（素材资产）时，需保证两者的 **ProjectName **一致 +> +> * Asset（素材资产）所属的 **ProjectName** 需与调用视频生成 API 接口时使用的 API key 所属的 **ProjectName** 一致 + +## 1. 创建素材资产组合 + +返回示例 + + + +## 2. 上传素材资产并获取素材资产信息 + +返回示例 + + + +更多语言的示例代码详见： + +> 注意替换 Demo 中的 AK与SK，若需调用其他接口如 ListAssets，需替换 ACTION 与对应请求参数。 + +| **Python** | 创建素材资产组合： 上传素材资产并获取素材资产信息： | +| ---------- | --------------------------- | +| **Java** | 创建素材资产组合： 上传素材资产并获取素材资产信息： | +| **PHP** | 创建素材资产组合： 上传素材资产： | + + + +## 3. 素材资产用于视频生成 + +> **注意：** +> 在传入给模型的 Prompt 中，需要使用**图片 1**、**视频 1 **的方式指代参考素材，素材序号为素材在请求体中的顺序。请勿直接在 Prompt 中直接使用 Asset ID。 +> 例：“**图片1 **里的女孩身着**图片2**中的服装，正在整理柜台上的物品。**图片3**中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。” +> +> 调用示例请参考[常见问题 4](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-YOKvdYHjro8EjtxucWaczf6vneg) + +当上传的素材资产状态为 `Active` 时，可将素材 Id 按 `asset: //` 的规则拼接 URL，以在 **视频生成 API **中使用对应的素材资产生成视频： + +使用素材资产生成视频的具体调用方式请参考[ 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）](https://bytedance.larkoffice.com/wiki/SANpwJ9bgiKgrykLaMTcAB0InWc#share-ONSwd51ezoXCJqxkAm2cIC61nMX)。 + + + +# 最佳实践--私域素材资产上传最佳案例 + +> 在上传素材资产时，**若将目标人脸图、全身参考图及细节参考图合并为同一张图片，可能导致各参考元素在画面中占比较小，从而增加模型识别难度**，造成生成视频中的人物形象与所上传素材资产出现偏差，或造成生成视频中素人脸被误识别为明星脸而触发风控拦截。 + +建议在上传素材资产时，将人物面部特写、服装细节等关键内容独立分割为单独的图片进行上传。具体可参考如下规则及示例： + +| | 应该 | 不应该 | | +| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词![图片1-背景参考图 (Token: BfvQbdPCDoJgGVx8x3zcMLoanHc)](images/BfvQbdPCDoJgGVx8x3zcMLoanHc.png)![图片2-人物妆造三视图 (Token: G0WaboKgVo3xo7xXxEGc8El6nLe)](images/G0WaboKgVo3xo7xXxEGc8El6nLe.png)![图片3-人物面部特写图 (Token: KIxBbnH6jonG19xgsqrcYkFEn7e)](images/KIxBbnH6jonG19xgsqrcYkFEn7e.png) | 给出背景参考图、人物妆造三视图、提示词![图片1-背景参考图 (Token: OnwKbbnpnojwcBxl1rucLDyQnJh)](images/OnwKbbnpnojwcBxl1rucLDyQnJh.png)![图片2-人物妆造三视图 (Token: ASc6b1QjJoi5owx1A9AccO0BnRd)](images/ASc6b1QjJoi5owx1A9AccO0BnRd.png) | | +| 输出内容 | | | | +| 总结 | 同样是古风打斗剧情：左边输入内容包括：背景参考图、**人物妆造三视图**、**人物面部无表情特写图**、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正视图、提示词。左边的输出视频更加还原人物面部特征；右边的人物面部特征一致性遵循不佳。 | | | +| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词![图片1-背景参考图 (Token: Y1ClbEmXPoKnp3xCV4MckLCWnQb)](images/Y1ClbEmXPoKnp3xCV4MckLCWnQb.jpeg)![图片2-人物妆造三视图 (Token: JYWCbGeXpo0QcgxFqQBcviGzn7b)](images/JYWCbGeXpo0QcgxFqQBcviGzn7b.jpeg)![图片3-人物面部特写图 (Token: Txwmbps9yoFd4ux6gOPcZoLEnkd)](images/Txwmbps9yoFd4ux6gOPcZoLEnkd.png)![图片4-人物妆造三视图 (Token: QDfrbDZLDo07MixPmPYcwGHLnjg)](images/QDfrbDZLDo07MixPmPYcwGHLnjg.jpeg)![图片5-人物面部特写图 (Token: Jj0XbeEGxoxNXUx8X2Lcy7BFnab)](images/Jj0XbeEGxoxNXUx8X2Lcy7BFnab.jpeg) | 给出背景参考图、人物妆造三视图、提示词![图片1-背景参考图 (Token: IJLmbyIAHoNI7KxFYb7cfkrBn0f)](images/IJLmbyIAHoNI7KxFYb7cfkrBn0f.jpeg)![图片2-人物妆造三视图 (Token: Zq9xbc7pyo1K8gxKbocclO9ZnPb)](images/Zq9xbc7pyo1K8gxKbocclO9ZnPb.jpeg)![图片3-人物妆造三视图 (Token: G8l5b5qXKoqyB0xfQNDcVOMRn9b)](images/G8l5b5qXKoqyB0xfQNDcVOMRn9b.jpeg) | 给出背景参考图、人物妆造正视图、提示词![图片1-背景参考图 (Token: CcIPbldwjoacLuxErVUcJA5CnPe)](images/CcIPbldwjoacLuxErVUcJA5CnPe.jpeg)![图片2-人物妆造正视图 (Token: BPutbuFU7oeJkfxE3KkcuOQUnAh)](images/BPutbuFU7oeJkfxE3KkcuOQUnAh.png)![图片3-人物妆造正视图 (Token: PUR8bJ0g5o6VsAxWhqpcnS9vn4l)](images/PUR8bJ0g5o6VsAxWhqpcnS9vn4l.png) | +| 输出内容 | | | | +| 总结 | 同样是温馨亲子剧情：左边输入内容包括：背景参考图、**人物妆造三视图、人物面部无表情特写图**、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正面图、提示词。左边的输出视频更加还原人物面部特征；中间的输出视频人物面部特征一致性遵循不佳；右边人物妆造、面部特征一致性遵循不佳。 | | | + diff --git a/docs/API文档/old-Seedance 2.0 & 2.0 fast API文档（邀测用户版）.md b/docs/API文档/old-Seedance 2.0 & 2.0 fast API文档（邀测用户版）.md new file mode 100644 index 0000000..969cf38 --- /dev/null +++ b/docs/API文档/old-Seedance 2.0 & 2.0 fast API文档（邀测用户版）.md @@ -0,0 +1,692 @@ +# 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版） + +该文档目前仅限开白客户使用，发送前请和销管确认客户是否在开白名单内 + +***【❗️❗️❗️】该文档限制客户申请权限，只有返回了服务协议的客户方可申请*** + +本文介绍 Seedance 2.0 & 2.0 fast 模型相较于存量模型 **新增/配置有区别 **的 API 参数介绍，存量 API 参数的完整介绍参见 [视频生成 API](https://www.volcengine.com/docs/82379/1520758?lang=zh)。 + +> 本文档仅限预览及邀测用户使用： +> +> * 不承诺正式API上线100%一致。 +> +> * 仅限邀测用户阅读，请勿截图/分享给其他人员。 +> +> * 您上传的内容请确保由您原创或已取得授权。 + +# 模型能力 + +> **Seedance 2.0 和 Seedance 2.0 fast 提供的模型能力一致，**追求最高生成品质，推荐使用 **Seedance 2.0**；更注重成本与生成速度，不要求极限品质，推荐使用 **Seedance 2.0 fast**。 + +**Seedance 2.0 & 2.0 fast (有声视频/无声视频)** + +* **多模态参考生视频**：输入参考图片（0\~9）+参考视频（0\~3）+ 参考音频（0\~3）+ 文本提示词（可选）生成 1 个目标视频。支持生成全新视频、编辑视频、延长视频。 + +> **注意：不可单独输入音频，应至少包含 1 个参考视频或图片。** + +* **图生视频-首尾帧**：输入首帧图片+尾帧图片+文本提示词（可选）生成 1 个目标视频。 + +* **图生视频-首帧**：输入首帧图片+文本提示词（可选）生成 1 个目标视频。 + +* **文生视频**：输入文本提示词生成 1 个目标视频。 + + + +**模型能力对比表：** + +| 模型名称 | | [Seedance 2.0](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-2-0) | [Seedance 2.0 fast](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-2-0-fast\&projectName=default) | [Seedance 1.5 pro](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-5-pro\&projectName=default) | [Seedance 1.0 pro ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-pro\&projectName=default) | [Seedance 1.0 pro fast ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-pro-fast\&projectName=default) | [Seedance 1.0 lite i2v](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-lite-i2v\&projectName=default) | [Seedance-1.0 lite t2v ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-lite-t2v) | +| ------------ | -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Model ID | | doubao-seedance-2-0-260128 | doubao-seedance-2-0-fast-260128 | doubao-seedance-1-5-pro-251215 | doubao-seedance-1-0-pro-250528 | doubao-seedance-1-0-pro-fast-251015 | doubao-seedance-1-0-lite-i2v-250428 | doubao-seedance-1-0-lite-t2v-250428 | +| 文生视频 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ | +| 图生视频-首帧 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ❌ | +| 图生视频-首尾帧 | | ✅ | | ✅ | ✅ | ❌ | ✅ | ❌ | +| 多模态参考【New】 | 图片参考 | ✅ | | ❌ | ❌ | ❌ | ✅ | ❌ | +| | 视频参考 | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ | +| | 组合参考 | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ | +| 编辑视频【New】 | | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ | +| 延长视频【New】 | | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ | +| 生成有声视频 | | ✅ | | ✅ | ❌ | ❌ | ❌ | ❌ | +| 联网搜索增强【New】 | | ✅ | | ❌ | [❌](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f359753773c94d97885008ca1223c9bc) | ❌ | ❌ | ❌ | +| 样片模式 | | ❌ | | ✅ | ❌ | ❌ | ❌ | ❌ | +| 返回视频尾帧 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ | +| 输出视频规格 | 输出分辨率 | 480p, 720p | | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | +| | 输出宽高比 | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | | | | | | | +| | 输出时长 | 4\~15 秒 | | 4\~12 秒 | 2\~12 秒 | 2\~12 秒 | 2\~12 秒 | 2\~12 秒 | +| | 输出视频格式 | mp4 | | mp4 | mp4 | mp4 | mp4 | mp4 | +| 离线推理 | | [❌](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f359753773c94d97885008ca1223c9bc) | | ✅ | ✅ | ✅ | ✅ | ✅ | +| 在线推理限流 | RPM | 600 | | 600 | 600 | 600 | 300 | 300 | +| | 并发数 | 10 | | 10 | 10 | 10 | 5 | 5 | +| 离线推理限流 | TPD | - | | 5000亿 | 5000亿 | 5000亿 | 2500亿 | 2500亿 | + + + + + +# Creat-创建视频生成任务 + +> POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks + +## 请求参数 + + + +#### **content** `object[]` `必选` + +输入给模型，生成视频的信息，支持文本、图片、音频、视频、样片任务 ID。支持以下几种组合： + +* **文本** + +* **文本（可选）+ 图片** + +* **文本（可选）+ 视频** + +* **文本（可选）+ 图片 + 音频** + +* **文本（可选）+ 图片 + 视频** + +* **文本（可选）+ 视频 + 音频** + +* **文本（可选）+ 图片 + 视频 + 音频** + +*** + +**信息类型：** + +* **文本信息**`object` + +输入给模型的提示词信息。 + +*** + +content.**type **`string` `必选` + +输入内容的类型，此处应为 **text**。 + +*** + +content.**text **`string` `必选` + +输入给模型的文本提示词，描述期望生成的视频。 + +支持中英文。建议中文不超过500字，英文不超过1000词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成视频缺失部分元素。提示词的更多使用技巧请参见 [Seedance 提示词指南](https://www.volcengine.com/docs/82379/1587797)。 + + + + + +* **图片信息** `object` + +输入给模型的图片信息。 + +*** + +content.**type **`string` `必选` + +输入内容的类型，此处应为 **image\_url**。 + +*** + +content.**image\_url **`object` `必选` + +输入给模型的图片对象。 + +*** + +content.image\_url.**url **`string` `必选` + +图片 URL 、图片 Base64 编码、素材 ID。 + +* 图片 URL：填入图片的公网 URL。 + +* Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式：data:image/<图片格式>;base64,\，注意 <图片格式> 需小写，如 data:image/png;base64,{base64\_image}。 + +* 素材 ID：用于视频生成的预置素材及虚拟人像的 ID，遵循格式：asset://\，可从 [素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128) 获取，详细使用请参见[文档](https://www.volcengine.com/docs/82379/2223965?lang=zh)。 + +> **传入单张图片要求** +> +> * 格式：jpeg、png、webp、bmp、tiff、gif +> +> * 宽高比（宽/高）： (0.4, 2.5) +> +> * 宽高长度（px）：(300, 6000) +> +> * 大小：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用Base64编码。 +> +> * 图片数量： +> +> * 图生视频-首帧：1 张 +> +> * 图生视频-首尾帧：2 张 +> +> * Seedance 2.0 & 2.0 fast 多模态参考生视频：1\~9 张 + +*** + +content.**role **`string` `条件必填` + +图片的位置或用途。 + +> **注意** +> +> * **图生视频-首帧**、**图生视频-首尾帧**、**多模态参考生视频**（包括参考图、视频、音频）为 3 种互斥场景，**不可混用**。 +> +> * **多模态参考生视频**可通过提示词指定参考图片作为首帧/尾帧，间接实现“首尾帧+多模态参考”效果。若需严格保障首尾帧和指定图片一致，**优先使用图生视频-首尾帧**（配置 role 为 **first\_frame / last\_frame**）。 + +*** + +**图生视频-首帧** + +> 需要传入1个 image\_url 对象 + +* **字段role取值：** + + * **first\_frame 或不填** + +*** + +**图生视频-首尾帧** + +> 需要传入2个 image\_url 对象 + +* **字段role取值：** + + * 首帧图片对应的字段 role 为：**first\_frame**，必填 + + * 尾帧图片对应的字段 role 为：**last\_frame**，必填 + +*** + +**图生视频-参考图 ** + +> 可传入 1\~9 个 image\_url 对象 + +* **字段role取值**： + + * 每张参考图对应的字段 role 均为：**reference\_image**，必填 + + + + + +* **视频信息** `object` + +输入给模型的视频信息。仅 Seedance 2.0 & 2.0 fast 支持输入视频。 + +*** + +content.**type **`string` `必选` + +输入内容的类型，此处应为 **video\_url**。 + +*** + +content.**video\_url **`object` `必选` + +输入给模型的视频对象。 + +*** + +content.video\_url.**url **`string` `必选` + +视频URL、素材 ID。 + +* 视频 URL：填入视频的公网 URL。 + +* 素材 ID：用于视频生成的预置素材及虚拟人像视频的 ID，遵循格式：asset://\。可从[素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128)获取。 + +> **传入单个视频要求** +> +> * 视频格式：mp4、mov。 +> +> * 分辨率：480p、720p +> +> * 时长：单个视频时长 \[2, 15] s，最多传入 3 个参考视频，所有视频总时长不超过 15s。 +> +> * 尺寸： +> +> * 宽高比（宽/高）：\[0.4, 2.5] +> +> * 宽高长度（px）：\[300, 6000] +> +> * 画面像素（宽 × 高）：\[409600, 927408] ，示例： +> +> * 画面尺寸 640×640=409600 满足最小值 ； +> +> * 画面尺寸 834×1112=927408 满足最大值。 +> +> * 大小：单个视频不超过 50 MB。 +> +> * 帧率 (FPS)：\[24, 60] + +*** + +content.**role **`string` `条件必填` + +视频的位置或用途。当前仅支持 **reference\_video**。 + + + + + +* **音频信息 **`object` + +输入给模型的音频信息。仅 Seedance 2.0 & 2.0 fast 支持输入音频。注意不可单独输入音频，应至少包含 1 个参考视频或图片。 + +*** + +content.**type **`string` `必选` + +输入内容的类型，此处应为 **audio\_url**。 + +*** + +content.**audio\_url **`object` `必选` + +输入给模型的音频对象。 + +*** + +content.audio\_url.**url **`string` `必选` + +音频 URL 、音频 Base64 编码、素材 ID。 + +* 音频 URL：填入音频的公网 URL。 + +* Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式：data:audio/<音频格式>;base64,\，注意 <音频格式> 需小写，如 data:audio/wav;base64,{base64\_audio}。 + +* 素材 ID：用于视频生成的虚拟人的音频素材 ID，遵循格式：asset://\。可从[素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128)获取。 + +> **传入单个音频要求** +> +> * 格式：wav、mp3 +> +> * 时长：单个音频时长 \[2, 15] s，最多传入 3 段参考音频，所有音频总时长不超过 15 s。 +> +> * 大小：单个音频不超过 15 MB，请求体大小不超过 64 MB。大文件请勿使用Base64编码。 + +*** + +content.**role **`string` `条件必填` + +音频的位置或用途。当前仅支持 **reference\_audio** 。 + + + +#### **service\_tier** `string` + + Seedance 2.0 & 2.0 fast 暂不支持 + + + +#### **generate\_audio **`boolean` + +> Seedance 2.0 & 2.0 fast 默认值： true + +控制生成的视频是否包含与画面同步的声音。 + +* true：模型输出的视频包含同步音频。模型会基于文本提示词与视觉内容，自动生成与之匹配的人声、音效及背景音乐。建议将对话部分置于双引号内，以优化音频生成效果。例如：男人叫住女人说：“你记住，以后不可以用手指指月亮。” + +* false：模型输出的视频为无声视频。 + +> **说明** +> +> 生成的有声视频均为单声道，和传入的音频声道数无关。 + +#### + +#### **draft **`boolean` + + Seedance 2.0 & 2.0 fast 暂不支持 + + + +#### **tools **`object[]` + +> 仅 Seedance 2.0 & 2.0 fast 支持 + +配置模型要调用的工具。 + +*** + +tools.**type **`string` + +指定使用的工具类型。 + +* web\_search：联网搜索工具。 + +> **说明** +> +> * 开启联网搜索后，模型会根据用户的提示词自主判断是否搜索互联网内容（如商品、天气等）。可提升生成视频的时效性，但也会增加一定的时延。 +> +> * 实际搜索次数可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 usage.tool\_usage.**web\_search** 字段获取，如果为 0 表示未搜索。 + + + +#### **resolution ** `string` + +> Seedance 2.0 & 2.0 fast 默认值：720p + +视频分辨率，取值范围： + +* 480p + +* 720p + + + +#### **ratio **`string` + +> Seedance 2.0 & 2.0 fast 默认值： adaptive + +生成视频的宽高比例。不同宽高比对应的宽高像素值见下方表格。 + +* 16:9 + +* 4:3 + +* 1:1 + +* 3:4 + +* 9:16 + +* 21:9 + +* adaptive：根据输入自动选择最合适的宽高比 + +> **adaptive 适配规则** +> +> 当配置 **ratio** 为 adaptive 时，模型会根据生成场景自动适配宽高比；实际生成的视频宽高比可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **ratio** 字段获取。 +> +> * 文生视频：根据输入的提示词，智能选择最合适的宽高比。 +> +> * 首帧 / 首尾帧生视频：根据上传的首帧图片比例，自动选择最接近的宽高比。 +> +> * 多模态参考生视频：根据用户提示词意图判断，如果是首帧生视频/编辑视频/延长视频，以该图片/视频为准选择最接近的宽高比；否则，以传入的第一个媒体文件为准（优先级：视频＞图片）选择最接近的宽高比。 + +*** + +**不同宽高比对应的宽高像素值：** + +| 分辨率 | 宽高比 | 宽高像素值 | +| ---- | ---- | -------- | +| 480p | 16:9 | 864×496 | +| | 4:3 | 752×560 | +| | 1:1 | 640×640 | +| | 3:4 | 560×752 | +| | 9:16 | 496×864 | +| | 21:9 | 992×432 | +| 720p | 16:9 | 1280×720 | +| | 4:3 | 1112×834 | +| | 1:1 | 960×960 | +| | 3:4 | 834×1112 | +| | 9:16 | 720×1280 | +| | 21:9 | 1470×630 | + + + +#### **duration** `integer` + +> Seedance 2.0 & 2.0 fast 默认值：5 + +生成视频时长，仅支持整数，单位：秒。 + +取值范围： + +* \[4,15] 或设置为-1 + +> **配置方法** +> +> * 指定具体时长：支持有效范围内的任一整数。 +> +> * 智能指定：设置为 -1，表示由模型在有效范围内自主选择合适的视频长度（整数秒）。实际生成视频的时长可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **duration** 字段获取。注意视频时长与计费相关，请谨慎设置。 + + + +#### **frames** `integer` + +Seedance 2.0 & 2.0 fast 暂不支持 + + + +#### **camera\_fixed** `boolean` + + Seedance 2.0 & 2.0 fast 暂不支持 + + + +# Get/List-查询视频生成任务/列表 + +> 查询视频生成任务：GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{id} +> +> 查询视频生成任务列表：GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?page\_num={page\_num}\&page\_size={page\_size}\&filter.status={filter.status}\&filter.task\_ids={filter.task\_ids}\&filter.model={filter.model} + +## 响应参数 + +#### **tools **`object[]` + +> 仅 Seedance 2.0 & 2.0 fast 支持 + +配置模型要调用的工具。 + +*** + +tools.**type **`string` + +指定使用的工具类型。 + +* web\_search：联网搜索工具。 + + + +#### **usage** `object` + +本次请求的 token 用量。 + +*** + +usage.**completion\_tokens** `integer` + +模型输出视频花费的 token 数量。 + +*** + +usage.**total\_tokens** `integer` + +本次请求消耗的总 token 数量。 + +*** + +usage.**tool\_usage **`object` + +> 仅 Seedance 2.0 & 2.0 fast 支持 + +使用工具的用量信息。 + +*** + +usage.tool\_usage.**web\_search **`integer` + +实际调用联网搜索工具的次数，仅开启联网搜索时返回。 + + + +# 调用简介及示例 + +## 流程简介 + +任务接口是异步接口，视频生成任务流程 + +1. 创建视频生成任务接口创建视频生成任务 + +2. 定时使用查询接口查询视频生成任务状态 + + 1. 任务 running，过段时间再查询任务状态 + + 2. 任务完成，返回视频链接，在24小时内下载生成的视频文件 + +## 1. 创建视频生成任务 + +> 以下示例仅展示 Seedance 2.0 & 2.0 fast 新增能力，更多视频生成示例详见 [创建视频生成任务 API](https://www.volcengine.com/docs/82379/1520757)。 + +### 多模态参考 + +### 编辑视频 + +### 延长视频 + +### 使用联网搜索 + +仅支持文本生视频 + +## 2. 查询视频生成任务 + +# 最佳实践-使用公共虚拟人像生成视频 + +平台提供公共虚拟人像素材库，目前您可以使用其中的图像素材来创建一个统一、完备的视频主角。帮助您更好地控制主角，并确保其形象在多段视频中保持一致，避免因为真人人脸限制导致角色无法统一的问题。 + +素材模态目前包含图片，并提供人物背景描述。每个素材对应一个独立素材 ID (asset ID)，在体验中心的视频生成任务中，指定角色人脸生成视频。 + +1. 在浏览器中打开[体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)，点击输入框下方的 **虚拟人像库** 页签。 + +2. 检索需要使用的人像，支持使用自然语言检索及筛选框组合筛选。 + +| 输入：文本 | 输入：虚拟人像、图片 | 输出 | +| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | +| **图片1**中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持**图片2**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 | ![Image Token: HTf6bPRukoWaW4xnCSlcvKtUn7c](images/HTf6bPRukoWaW4xnCSlcvKtUn7c.png)![Image Token: YfCDbzJlqo4yzZxCmdscWdsInCf](images/YfCDbzJlqo4yzZxCmdscWdsInCf.jpeg) | | + + + +在 [Video Generation API](https://www.volcengine.com/docs/82379/1520758) 的 **content.<模态>\_url.url** 字段中使用 素材 URI 生成视频。 + +> 输入的参考内容，包括人像素材，需符合视频生成限制，具体信息请查看使用限制。 +> +> **注意**： +> +> * 首次在 API 中使用虚拟人像素材 Asset URI 前，需先在[方舟体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)提交一次视频生成任务，阅读并同意弹出的 **虚拟人像库使用协议**。 +> +> * 体验中心支持体验视频生成能力。默认单次生成 4 段视频，为节约成本，建议设置为每次生成 1 条，具体方式可参考[虚拟人像库](https://www.volcengine.com/docs/82379/2223965?lang=zh)。 + +同意协议的操作方式如下： + +![Image Token: LK8ybUN9Ko2KkQxq2FdclVQtnkh](images/LK8ybUN9Ko2KkQxq2FdclVQtnkh.gif) + +示例代码： + +# 使用自有虚拟人像素材生成视频（线下提交） + +方舟提供私域人像素材库，您可在视频生成中使用自有虚拟人物或真人（仅限素人）素材，生成短剧等更定制化的视频内容。平台将对您提供的素材进行审核，规避可能产生的法律风险。 + +* 自有素材需入库后使用，您可将虚拟人像或真人素材发送给销售代表，同时完成合规承诺函及其他证明材料的准备。 + +* 入库后，您可使用素材的 Asset ID，在视频生成 API 中使用自有素材。 + +> **重要**： +> +> * 对虚拟人像素材，您需签署虚拟人像素材合规承诺函，并提供签署承诺函所需的材料。 +> +> * 对真实人物素材，除承诺函外，您还需额外提供真人授权材料。 +> +> * 具体流程及所需材料，请和您的销售代表确认。 + +提交自有人像素材时，需按人物将素材分组： + +* 每个人物为一个素材组。 + +* 每组可包含多个素材文件，素材文件对应唯一 ID (asset ID)。 + +## 入库流程 + +提交自有虚拟人像素材方式大致如下，请联系您的销售代表了解详情。 + +1. 准备素材文件，完成承诺函签署，并准备其他证明材料。 + +2. 准备素材文件，完成承诺函签署，并准备其他证明材料。 + + * 每个人物素材需至少提供一张正面图片文件。此外，您可按需提供该人物的其他图片、视频素材。 + + * 需确保每个人物组中的素材与该正面图片为同一人物。 + + * 每个人物创建一个文件夹（命名：“*虚拟人像 1-<人像名>*”） + + 提交素材文件夹示例： + + ![Image Token: XMQ9bz6vhof7vxxsac8cqIZmneB](images/XMQ9bz6vhof7vxxsac8cqIZmneB.png) + + > **注意**： + > + > * 以上示例仅供参考，您可根据视频创作需求，提交虚拟人物素材。 + > + > * 您仅需上传视频生成任务中需要使用的素材。 + + * 素材文件需满足视频生成 API 对输入文件的要求： + + > **传入单张图片要求** + > + > * 格式：jpeg、png、webp、bmp、tiff、gif + > + > * 宽高比（宽/高）： (0.4, 2.5) + > + > * 宽高长度（px）：(300, 6000) + > + > * 大小：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用Base64编码。 + + + + > **传入单个视频要求** + > + > * 视频格式：mp4、mov。 + > + > * 分辨率：480p、720p + > + > * 时长：单个视频时长 \[2, 15] s，最多传入 3 个参考视频，所有视频总时长不超过 15s。 + > + > * 尺寸： + > + > * 宽高比（宽/高）：\[0.4, 2.5] + > + > * 宽高长度（px）：\[300, 6000] + > + > * 画面像素（宽 × 高）：\[409600, 927408] ，示例： + > + > * 画面尺寸 640×640=409600 满足最小值 ； + > + > * 画面尺寸 834×1112=927408 满足最大值。 + > + > * 大小：单个视频不超过 50 MB。 + > + > * 帧率 (FPS)：\[24, 60] + + + + > **注意**： + > + > 有关提交流程、承诺函签署所需材料的具体信息，请联系您的销售代表了解详情。 + +3. 方舟将对您提供的素材进行审核，通过审核的素材将被上传至虚拟人像库。 + +4. 入库后，每个人物组素材将通过以下示例中的形式返回，您可解压后查看： + + ![Image Token: PKu6b3391oUbVKxxEGjchxBVnbg](images/PKu6b3391oUbVKxxEGjchxBVnbg.png) + +示例中： + +* Andy 为您提交的人物名称 + +* group-20260310035119-9mzqn 为该人物组的 ID + +* 解压后，可查看每张素材的 Asset ID，如： + +![Image Token: VV0ybrxNfouEhZxTjqCcX1epnzb](images/VV0ybrxNfouEhZxTjqCcX1epnzb.png) + +* 您可按 `asset: //` 规则拼接 URI，在 API 中使用对应素材生成视频： + +具体调用方式请参考 [最佳实践-使用虚拟人像生成视频](https://bytedance.larkoffice.com/wiki/SANpwJ9bgiKgrykLaMTcAB0InWc#share-YurKdrLfAocLErxsTWDcKidPnGd)。 + +## **注意事项** + +1. 首次在 API 中使用虚拟人像素材 Asset URI 前，需先在[方舟体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)提交一次视频生成任务，阅读并同意弹出的 **虚拟人像库使用协议**，操作方式如下： + +![Image Token: IFfPbDgceoFXZCxdriIcnwkPnUc](images/IFfPbDgceoFXZCxdriIcnwkPnUc.gif) + +* 仅支持使用已入库素材生成视频。 diff --git a/docs/API文档/old-「保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）.md b/docs/API文档/old-「保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）.md new file mode 100644 index 0000000..75cb4f3 --- /dev/null +++ b/docs/API文档/old-「保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）.md @@ -0,0 +1,1201 @@ +# 「⚠️保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版） + +本文介绍素材资产（Assets）API 接口的参数。您可以使用以下 Assets API 接口创建、管理个人人像素材资产。 + +> 本文档仅限预览及邀测用户使用： +> +> * 不承诺正式 API 上线100%一致。 +> +> * 仅限邀测用户阅读，请勿截图/分享给其他人员。 +> +> * 您需确保上传的虚拟人像符合以下条件： +> +> * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。 +> +> * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。 +> +> * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。 + + + +# 素材资产（Assets）API 接口功能 + +> **素材资产的概念说明：** +> +> * **Asset（素材资产）**：一个素材文件（图片），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。 +> +> * 仅需入库推理需使用的素材资产，不需使用的素材资产请勿入库。 +> +> * 仅可使用已入库素材资产的 Id (Asset ID) 进行视频生成，同一形象未入库素材无法使用。 +> +> * **Asset Group（素材资产组合）**：单个素材文件为一个 Asset，每个 Asset 属于一个 Asset Group。 +> +> * 可以使用素材组自由管理素材，例如可将同一人物、同一工作室或项目组的素材放入同一素材组合进行管理。 + +**Asset (Group) 创建接口：** + +1. CreateAssetGroup：创建素材资产组合。**首次创建素材资产组合时需在控制台签署授权函，详情参考 [ 私域虚拟人像素材库 (WIP)](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)** + +2. CreatAsset：创建素材资产。该接口可用于上传个人素材资产，创建素材资产后可利用返回字段中的素材 **Id （需处于 `active` 状态）**用于 Seedance 2.0 系列模型生成视频。 + + + +**Asset (Group) 管理接口：** + +* ListAssetGroups：查询素材资产组合列表。 + +* ListAssets：查询素材资产列表。 + +* GetAsset：查询素材资产信息。 + +* GetAssetGroup：查询素材资产组合信息。 + +* UpdateAssetGroup：更新素材资产组合信息。 + +* UpdateAsset：更新素材资产信息。 + + + +# 鉴权方式 + +调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [获取 API 访问密钥（AK/SK）](https://www.volcengine.com/docs/6257/64983?lang=zh)。 + + + +# 限流要求 + +* 并发数限制：账号下同一时刻在处理中的任务数量上限，超过此限制的任务将进入队列等待处理。**同时进行处理的asset创建任务不超过30。** + +* QPS 限流： API接口每秒查询请求的总数上限。超过此限制的查询请求会报错。 + +| 接口名 | 账号维度的 QPS 限流 | +| ---------------- | ------------ | +| CreateAssetGroup | 30 | +| CreateAsset | 30 | +| ListAssetGroups | 30 | +| ListAssets | 30 | +| GetAsset | 100 | +| GetAssetGroup | 100 | +| UpdateAsset | 30 | +| UpdateAssetGroup | 30 | + +# CreateAssetGroup + +> **POST **/open/CreateAssetGroup + +创建 Asset Group（素材资产组合）组合，用作素材资产管理。 + +> **首次创建 Asset Group（素材资产组合）需在控制台签署授权函，详情参考 [ 私域虚拟人像素材库 (WIP)](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)** + +### **Name** `string` `必填` + +Asset Group（素材资产组合）的名称，上限为 64 字符。 + +*** + +### **Description** `string` + +Asset Group（素材资产组合）的描述，上限为 300 字符。 + +*** + +### **GroupType **`string` + +Asset Group（素材资产组合）的类型。可选值： + +* AIGC：虚拟人像。 + +*** + +### **ProjectName **`string`** ** + +资源所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id** `string` + +Asset Group（素材资产组合）的 Id。 + +*** + +返回示例： + +```bash +{ + "Id": "group-2026**********-*****" +} +``` + + + +# CreateAsset + +> **POST **/open/CreateAsset + +向指定的Asset Group（素材资产组合）内创建Asset（素材资产）。 + + + +## 请求参数 + +### **GroupId** `string` `必填` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +### **URL** `string` `必填` + +传入的Asset（素材资产）的公共可访问地址。 + +*** + +### **Name** `string` + +Asset（素材资产）的名称，上限为64个字符。 + +*** + +### **AssetType `string` `必填`** + +Asset（素材资产）的类型，当前仅支持传入图像。可选值： + +* Image：Asset（素材资产）的类型为图像。 + +> **传入图像的要求说明** +> +> * 格式：jpeg、png、webp、bmp、tiff、gif、heic/heif +> +> * 宽高比（宽/高）： (0.4, 2.5) +> +> * 宽高长度（px）：(300, 6000) +> +> * 大小：单张图片小于 30 MB。 + +*** + +### **ProjectName** `string` + +资源所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +> 需要和待传入的 Asset Group（素材资产组合）的 **ProjectName **保持一致。 + +*** + + + +## 返回参数 + +### **Id **`string` + +Asset（素材资产）的 Id。 + +*** + +返回示例： + +```bash +{ + "Id": "Asset-2026**********-*****" +} +``` + + + +# ListAssets + +> **POST **/open/ListAssets + +查询符合筛选条件的Assets（素材资产）列表。 + +## 请求参数 + +### **Filter** `object` `必填` + +搜索的过滤条件。 + +*** + +Filter.**GroupIds** `array` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +Filter.**GroupType** `string` `必填` + +Asset Group（素材资产组合）的类型。可选值： + +* AIGC：虚拟人像。 + +*** + +Filter.**Statuses** `array`** ** + +任务状态。 + +* Active：素材资产（Asset）已处理完毕，可以使用。 + +* Processing：素材资产（Asset）正在预处理，无法使用。 + +* Failed：素材资产（Asset）处理失败。 + +*** + +Filter.**Name** `string`** ** + +Asset（素材资产）的名称，上限为64个字符。 + +*** + +### **PageNumber** `int (i64)` `必填` + +搜索页码，可用于列表分页功能，从 1 开始。例如："page\_number": 1，即返回第一页的搜索结果。 + +*** + +### **PageSize** `int (i64)` `必填` + +每页搜索结果的数量，上限为100。 + +*** + +### **SortBy** `string` + +用于排序的字段名称，默认值 `createTime`。支持以下类型： + +* CreateTime：根据创建时间排序。 + +* UpdateTime：根据更新时间排序。 + +* GroupId：根据资产素材组的 Id 排序。 + +*** + +### **SortOrder** `string` + +排序顺序，默认值 `Desc`。可选值： + +* Desc：降序 + +* Asc：升序 + +*** + +### **ProjectName** `string` + +资源所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Items** `array[]` + +符合筛选条件的Asset（素材资产）数组。 + +*** + +Items.**Id** `string` + +Asset（素材资产）的 Id。 + +*** + +Items.**name** `string` + +Asset（素材资产）的名称，上限为64个字符。 + +*** + +Items.**URL** `string` + +Asset（素材资产）的公共可访问地址。 + +*** + +Items.**GroupId** `string` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +Items.**AssetType** `string` + +Asset（素材资产）的类型。 + +* Image：Asset（素材资产）的类型为图像。 + +*** + +Items.**Status** `string` + +任务状态。 + +* Active：素材资产（Asset）已处理完毕，可以使用。 + +* Processing：素材资产（Asset）正在预处理，无法使用。 + +* Failed：素材资产（Asset）处理失败。 + +*** + +Items.**Error** `object` + +错误信息。 + +*** + +Items.Error.**Code** `string` + +错误码。 + +*** + +Items.Error.**Message** `string` + +错误信息。 + +*** + +Items.**ProjectName** `string` + +资源所属的项目名称。 + +*** + +Items.**CreateTime **`string` + +创建时间。 + +*** + +Items.**UpdateTime **`string` + +更新时间。 + +*** + +### **TotalCount **`int (i64)` + +返回总数。 + +*** + +### **PageNumber **`int (i64)` + +返回的页数。 + +*** + +### **PageSize **`int (i64)` + +每页搜索结果的数量，上限为100。 + + + +# ListAssetGroups + +> **POST **/open/ListAssetGroups + +查询符合筛选条件的Asset Groups（素材资产组合）列表。 + +## 请求参数 + +### **Filter** `object` `必填` + +搜索的过滤条件。 + +*** + +Filter.**name** `string` + +Asset Group（素材资产组合）的名称，上限为64个字符。 + +*** + +Filter.**GroupIds** `array` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +Filter.**GroupType** `string`** **`必填` + +Asset Group（素材资产组合）的类型。可选值： + +* AIGC：虚拟人像。 + +*** + +### **PageNumber** `int (i64)` + +搜索页码，可用于列表分页功能，从 1 开始。例如："page\_number": 1，即返回第一页的搜索结果。 + +*** + +### **PageSize** `int (i64)` + +每页搜索结果的数量，上限为100。 + +*** + +### **SortBy** `string` + +用于排序的字段名称，默认值 `createTime`。支持以下类型： + +* CreateTime：根据创建时间排序。 + +* UpdateTime：根据更新时间排序。 + +*** + +### **SortOrder** `string` + +排序顺序，默认值 `Desc`。可选值： + +* Desc：降序 + +* Asc：升序 + +*** + +### **ProjectName** `string` + +资源所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **TotalCount **`int (i64)` + +返回的 Asset Group（素材资产组合）的总数。 + +*** + +### **Items** `array[]` + +符合筛选条件的 Asset Group（素材资产组合）数组。 + +*** + +Items.**Id** `string` + +Asset Group（素材资产组合）的 Id。 + +*** + +Items.**Name** `string` + +Asset Group（素材资产组合）的名称，上限为64个字符。 + +*** + +Items.**Title** `string` + +Asset Group（素材资产组合）的标题。 + +> 即将下线，请直接使用参数 Name + +*** + +Items.**Description** `string` + +Asset Group（素材资产组合）的描述，上限为 300 字符。 + +*** + +Items.**GroupType** `string` + +Asset Group（素材资产组合）的类型。 + +* AIGC：虚拟人像。 + +*** + +Items.**ProjectName** `string` + +资源所属的项目名称。 + +*** + +Items.**CreateTime** `string` + +创建时间。 + +*** + +Items.**UpdateTime** `string` + +更新时间。 + +*** + +### **PageNumber **`int (i64)` + +返回的页数。 + +*** + +### **PageSize **`int (i64)` + +每页搜索结果的数量，上限为100。 + +*** + + + +# GetAssetGroup + +> **POST **/open/GetAssetGroup + +获取单个Asset Group（素材资产组合）信息。 + +## 请求参数 + + + +### **Id **`string` `必填` + +Asset Group（素材资产组合）的 Id + +*** + +### **ProjectName **`string` + +需要查询的 Asset Group（素材资产组合）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id** `string` + +Asset Group（素材资产组合）的 Id。 + +*** + +### **Name** `string` + +Asset Group（素材资产组合）的名称，上限为64个字符。 + +*** + +### **Title** `string` + +Asset Group（素材资产组合）的标题。 + +> 即将下线，请直接使用参数 Name + +*** + +### **Description** `string` + +Asset Group（素材资产组合）的描述，上限为 300 字符。 + +*** + +### **GroupType **`string` + +Asset Group（素材资产组合）的类型。 + +* AIGC：虚拟人像 + +*** + +### **ProjectName **`string`** ** + +资源所属的项目名称。 + +*** + +### **CreateTime **`string` + +创建时间。 + +*** + +### **UpdateTime **`string` + +更新时间。 + +*** + +## + +# GetAsset + +> **POST **/open/GetAsset + +获取单个Asset（素材资产）信息。 + +## 请求参数 + + + +### **Id **`string` `必填` + +Asset（素材资产）的 Id。 + +*** + +### **ProjectName **`string` + +需要查询的 Asset（素材资产）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id **`string` + +Asset（素材资产）的 Id。 + +*** + +### **Name** `string` + +Asset（素材资产）的名称，上限为64个字符。 + +*** + +### **URL **`string` + +Asset（素材资产）的访问地址。 + +*** + +### **AssetType **`string` + +Asset（素材资产）的类型。 + +* Image：Asset（素材资产）的类型为图像。 + +*** + +### **GroupId** `string` + +Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。 + +*** + +### **Status** `string` + +任务状态。 + +* Active：素材资产（Asset）已处理完毕，可以使用。 + +* Processing：素材资产（Asset）正在预处理，无法使用。 + +* Failed：素材资产（Asset）处理失败。 + +*** + +### **Error** `object` + +错误信息。 + +*** + +Error.**Code** `string` + +错误码。 + +*** + +Error.**Message** `string` + +错误信息。 + +*** + +### **CreateTime **`string` + +创建时间。 + +*** + +### **UpdateTime ** `string` + +更新时间。 + +*** + +### **ProjectName** `string` + +资源所属的项目名称。 + +*** + +## + +# **UpdateAssetGroup** + +> **POST **/open/UpdateAssetGroup + +更新单个 Asset Group（素材资产组合）信息。当前仅支持更新 Asset Group（素材资产组合）的 Name 和 Description。 + +## 请求参数 + +### **Id **`string` `必填` + +需要更新的 Asset Group（素材资产组合）的 Id + +*** + +### **Name **`string` + +需要更新的 Asset Group（素材资产组合）的新名称，上限为64个字符。 + +*** + +### **Description** `string` + +需要更新的 Asset Group（素材资产组合）的新描述，上限为 300 字符。 + +*** + +### **ProjectName** `string` + +需要更新的 Asset Group（素材资产组合）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id** `string` + +Asset Group（素材资产组合）的 Id。 + +*** + + + + + +# **UpdateAsset** + +> **POST **/open/UpdateAsset + +更新单个Asset（素材资产）信息。当前仅支持更新Asset（素材资产）的 Name。 + +## 请求参数 + +### **Id **`string` `必填` + +需要更新的 Asset（素材资产）的 Id + +*** + +### **Name **`string` + +需要更新的 Asset（素材资产）的新名称，上限为64个字符。 + +*** + +### **ProjectName** `string` + +需要更新的 Asset（素材资产）所属的项目名称，默认值为`default`。 + +若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +*** + + + +## 返回参数 + +### **Id** `string` + +Asset（素材资产）的 Id。 + +*** + + + +# 代码示例： + +> **以下示例为使用 Asset API 创建素材资产并用于视频生成的使用链路：** +> +> 1. **创建素材资产组合：**调用 **CreateAssetGroup** 接口创建一个素材资产组合（Asset Group），用于对同一项目或人物的素材进行统一管理。首次创建时需在控制台签署授权函。 +> +> 2. **上传素材资产并等待预处理完成：**调用 **CreateAsset** 接口上传图片素材，传入图片的公共访问URL及所属的Group ID，获得素材资产ID（Asset ID）。 +> 由于上传的素材资产需经过预处理后才能使用，可轮询调用 **GetAsset** 接口查询素材状态，直至状态变为 `Active`。若状态为 `Failed` 则表示处理失败。 +> +> 3. **在视频生成 API 中使用素材：**当素材资产状态为 `Active` 后，将素材ID按 `Asset://` 的格式拼接成URL，在视频生成API（如Seedance 2.0系列模型）的请求中，将该URL作为参考图像的 `image_url` 传入，即可使用该素材资产生成视频。 +> +> **API 鉴权方式区别说明** +> +> * **Asset API：**Access Key 鉴权，详情参考 [获取 API 访问密钥（AK/SK）](https://www.volcengine.com/docs/6257/64983?lang=zh)。 +> +> * **视频生成 API：**API Key 鉴权，详情参考 [管理 API Key](https://www.volcengine.com/docs/82379/1361424?lang=zh)。 +> +> **素材库[项目](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)（Project）隔离说明** +> +> * 向指定的 Asset Group（素材资产组合）内创建或查询 Asset（素材资产）时，需保证两者的 **ProjectName **一致 +> +> * Asset（素材资产）所属的 **ProjectName** 需与调用视频生成 API 接口时使用的 API key 所属的 **ProjectName** 一致 + +## 1. 创建素材资产组合 + +```go +package main + +import ( + "fmt" + + "github.com/bytedance/sonic" + "github.com/volcengine/volcengine-go-sdk/volcengine" + "github.com/volcengine/volcengine-go-sdk/volcengine/credentials" + "github.com/volcengine/volcengine-go-sdk/volcengine/session" + "github.com/volcengine/volcengine-go-sdk/volcengine/universal" +) + +func main() { + config := volcengine.NewConfig().WithCredentials(credentials.NewStaticCredentials("", "", "")).WithRegion("cn-beijing") + sess, _ := session.NewSession(config) + resp, err := universal.New(sess).DoCall( + universal.RequestUniversal{ + ServiceName: "ark", + Action: "CreateAssetGroup", + Version: "2024-01-01", + HttpMethod: universal.POST, + ContentType: universal.ApplicationJSON, + }, + //根据实际情况填写 + &map[string]any{ + "Name": "test", + "Description": "test", + "GroupType": "AIGC", + }, + ) + if err != nil { + return + } + if resp == nil { + return + } + respData, err := sonic.Marshal(resp) + fmt.Println(string(respData)) +} +``` + +返回示例 + +```json +{"ResponseMetadata":{"RequestId":"20260318155041036F7CB6362358FB40FC","Action":"CreateAssetGroup","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},"Result":{"Id":"group-2026**********-*****"}} +``` + + + +## 2. 上传素材资产并获取素材资产信息 + +```go +package main + +import ( + "errors" + "fmt" + "time" + + "github.com/bytedance/sonic" + "github.com/volcengine/volcengine-go-sdk/volcengine" + "github.com/volcengine/volcengine-go-sdk/volcengine/credentials" + "github.com/volcengine/volcengine-go-sdk/volcengine/session" + "github.com/volcengine/volcengine-go-sdk/volcengine/universal" +) + +const ( + region = "cn-beijing" + serviceName = "ark" + version = "2024-01-01" + + // 轮询配置 + pollInterval = 3 * time.Second + pollTimeout = 2 * time.Minute +) + +func main() { + // TODO: 替换为你的 AK / SK + ak := "" + sk := "" + + // TODO: 替换为你的实际参数 + groupID := "" + assetURL := "" + assetType := "Image" + projectName := "Default" + + config := volcengine.NewConfig(). + WithCredentials(credentials.NewStaticCredentials(ak, sk, "")). + WithRegion(region) + + sess, err := session.NewSession(config) + if err != nil { + fmt.Printf("create session failed: %v\n", err) + return + } + + client := universal.New(sess) + + // 1. 创建素材资产 + assetID, err := createAsset(client, groupID, assetURL, assetType, projectName) + if err != nil { + fmt.Printf("create asset failed: %v\n", err) + return + } + + fmt.Printf("asset created, AssetId = %s\n", assetID) + + // 2. 查询素材资产状态 + finalURL, err := waitForAssetActive(client, assetID, pollInterval, pollTimeout) + if err != nil { + fmt.Printf("poll asset failed: %v\n", err) + return + } + + fmt.Printf("asset is active, URL = %s\n", finalURL) +} + +// createAsset 调用 CreateAsset 并返回 AssetId +func createAsset(client *universal.Universal, groupID, url, assetType, projectName string) (string, error) { + resp, err := client.DoCall( + universal.RequestUniversal{ + ServiceName: serviceName, + Action: "CreateAsset", + Version: version, + HttpMethod: universal.POST, + ContentType: universal.ApplicationJSON, + }, + &map[string]any{ + "GroupId": groupID, + "URL": url, + "AssetType": assetType, + "ProjectName": projectName, + }, + ) + if err != nil { + return "", err + } + if resp == nil { + return "", errors.New("create asset response is nil") + } + + // 打印原始返回，便于排查 + respData, _ := sonic.Marshal(resp) + fmt.Printf("CreateAsset response: %s\n", string(respData)) + + assetID := extractString(resp, "Result", "Id") + if assetID == "" { + assetID = extractString(resp, "Result", "AssetId") + } + if assetID == "" { + assetID = extractString(resp, "Id") + } + if assetID == "" { + assetID = extractString(resp, "AssetId") + } + + if assetID == "" { + return "", fmt.Errorf("cannot find AssetId in response: %s", string(respData)) + } + + return assetID, nil +} + +// waitForAssetActive 查询 GetAsset，直到 Active / Failed / 超时 +func waitForAssetActive(client *universal.Universal, assetID string, interval, timeout time.Duration) (string, error) { + deadline := time.Now().Add(timeout) + + for { + if time.Now().After(deadline) { + return "", fmt.Errorf("polling timeout after %v, assetID=%s", timeout, assetID) + } + + status, url, errMsg, err := getAssetStatus(client, assetID) + if err != nil { + return "", err + } + + fmt.Printf("asset status: %s\n", status) + + switch status { + case "Processing": + time.Sleep(interval) + continue + case "Active": + if url == "" { + return "", fmt.Errorf("asset is Active but URL is empty, assetID=%s", assetID) + } + return url, nil + case "Failed": + if errMsg == "" { + errMsg = "unknown asset processing error" + } + return "", fmt.Errorf("asset processing failed: %s", errMsg) + default: + // 若返回其他状态，保守处理为继续查询 + fmt.Printf("unexpected status %q, continue polling...\n", status) + time.Sleep(interval) + } + } +} + +// getAssetStatus 调用 GetAsset，返回 Status / URL / Error +func getAssetStatus(client *universal.Universal, assetID string) (status, url, errMsg string, err error) { + resp, err := client.DoCall( + universal.RequestUniversal{ + ServiceName: serviceName, + Action: "GetAsset", + Version: version, + HttpMethod: universal.POST, + ContentType: universal.ApplicationJSON, + }, + &map[string]any{ + "Id": assetID, + }, + ) + if err != nil { + return "", "", "", err + } + if resp == nil { + return "", "", "", errors.New("get asset response is nil") + } + + // 打印原始返回，便于排查 + respData, _ := sonic.Marshal(resp) + fmt.Printf("GetAsset response: %s\n", string(respData)) + + // 兼容不同层级的字段位置 + status = extractString(resp, "Result", "Status") + if status == "" { + status = extractString(resp, "Status") + } + + url = extractString(resp, "Result", "URL") + if url == "" { + url = extractString(resp, "URL") + } + + errMsg = extractString(resp, "Result", "Error") + if errMsg == "" { + errMsg = extractString(resp, "Error") + } + + return status, url, errMsg, nil +} + +// extractString 从响应中按层级安全提取字符串 +func extractString(data any, keys ...string) string { + current := data + + for _, key := range keys { + switch v := current.(type) { + case map[string]any: + next, ok := v[key] + if !ok { + return "" + } + current = next + + case *map[string]any: + if v == nil { + return "" + } + next, ok := (*v)[key] + if !ok { + return "" + } + current = next + + default: + return "" + } + } + + switch v := current.(type) { + case string: + return v + case fmt.Stringer: + return v.String() + case nil: + return "" + default: + return fmt.Sprintf("%v", v) + } +} +``` + +返回示例 + +```json +CreateAsset response: {"ResponseMetadata":{"RequestId":"202603181520431F067112A17FC078A6DF","Action":"CreateAsset","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},"Result":{"Id":"Asset-2026**********-*****"}} +asset created, AssetId = asset-20260318072044-n8bcl +GetAsset response: {"ResponseMetadata":{"Service":"ark","Region":"cn-beijing","RequestId":"202603181520448A995106924553F77D0E","Action":"GetAsset","Version":"2024-01-01"},"Result":{"Name":"","GroupId":"group-2026**********-*****","CreateTime":"2026-03-18T07:20:44Z","ProjectName":"default","Id":"Asset-2026**********-*****","URL":"","AssetType":"Image","Status":"Processing","UpdateTime":"2026-03-18T07:20:44Z"}} +asset status: Processing +GetAsset response: {"Result":{"UpdateTime":"2026-03-18T07:20:47Z","ProjectName":"default","Id":"Asset-2026**********-*****","CreateTime":"2026-03-18T07:20:44Z","Name":"","URL":"","AssetType":"Image","GroupId":"group-2026**********-*****","Status":"Processing"},"ResponseMetadata":{"Version":"2024-01-01","Service":"ark","Region":"cn-beijing","RequestId":"2026031815204766FE2BA543E6FF666F66","Action":"GetAsset"}} +asset status: Processing +GetAsset response: {"ResponseMetadata":{"Version":"2024-01-01","Service":"ark","Region":"cn-beijing","RequestId":"202603181520511F067112A17FC078A75A","Action":"GetAsset"},"Result":{"Name":"","URL":"https://ark-media-asset-stg.tos-cn-beijing.volces.com/xxxx","AssetType":"Image","Status":"Active","Id":"Asset-2026**********-*****","GroupId":"group-2026**********-*****","CreateTime":"2026-03-18T07:20:44Z","UpdateTime":"2026-03-18T07:20:47Z","ProjectName":"default"}} +asset status: Active +asset is active, URL = https://ark-media-asset-stg.tos-cn-beijing.volces.com/xxxx +``` + + + +更多语言的示例代码详见： + +> 注意替换 Demo 中的 AK与SK，若需调用其他接口如 ListAssets，需替换 ACTION 与对应请求参数。 + +| **Python** | 创建素材资产组合： 上传素材资产并获取素材资产信息： | +| ---------- | --------------------------- | +| **Java** | 创建素材资产组合： 上传素材资产并获取素材资产信息： | +| **PHP** | 创建素材资产组合： 上传素材资产： | + + + +## 3. 素材资产用于视频生成 + +当上传的素材资产状态为 `Active` 时，可将素材 Id 按 `Asset: //` 的规则拼接 URL，以在 **视频生成 API **中使用对应的素材资产生成视频： + +```json + { + "type": "image_url", + "image_url": { + "url": "Asset://Asset-2026**********-*****" + }, + "role": "reference_image" + }, +``` + +使用素材资产生成视频的具体调用方式请参考[ 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）](https://bytedance.larkoffice.com/wiki/SANpwJ9bgiKgrykLaMTcAB0InWc#share-ONSwd51ezoXCJqxkAm2cIC61nMX)。 + diff --git a/docs/API文档/「保密信息」【申请权限填客户名称】控制台上传自有虚拟人像至素材资产库（邀测用户版）.md b/docs/API文档/「保密信息」【申请权限填客户名称】控制台上传自有虚拟人像至素材资产库（邀测用户版）.md new file mode 100644 index 0000000..acb3826 --- /dev/null +++ b/docs/API文档/「保密信息」【申请权限填客户名称】控制台上传自有虚拟人像至素材资产库（邀测用户版）.md @@ -0,0 +1,128 @@ +# 「⚠️保密信息」【申请权限填客户名称】控制台上传自有虚拟人像至素材资产库（邀测用户版） + +> 请注意，仅开白用户在控制台可见**《上传虚拟人像素材合规承诺函》**的签署入口，若仅可见**《素材资产功能使用规则》**，则需申请开白 + +# 1. 介绍 + +3月19日起功能上线后，火山方舟会在控制台支持完成开白的B端客户批量上传和管理虚拟人资产，同时支持使用API创建、管理，允许企业上传**自有AIGC虚拟人**（含品牌定制 IP、自制数字人、采购的合规虚拟人等），在线勾选确认**《上传虚拟人像素材合规承诺函》**，承诺上传的虚拟人像为企业合法所有、未侵犯任何第三方权益、不与任何自然人的肖像形象相同或相似、仅用于合规用途，即可完成确权，将虚拟人像上传入库，在推理中使用，仅可使用已入库的素材资产进行视频生成，未入库素材，即使为已入库同一角色的不同妆造，也无法使用。 + + + +# 2. 使用流程 + +![画板 1](images/whiteboard_1_1774075398978.png) + +| | 释义 | 举例 | +| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **素材资产（Asset）** | 一个素材文件（本期**仅支持图片**），是方舟Seedance系列模型可直接用于推理的可信资产 | ![Image Token: QwfCbg7HWodX84x6Jwdl8iWxg6d](images/QwfCbg7HWodX84x6Jwdl8iWxg6d.png) | +| **资产组合（Group）** | 将原子化的资产（Asset）组合起来，可以人物、工作室、项目组等维度将素材进行分组管理 | ![Image Token: KXmAbBvXTophYGxhUzulqOfWgab](images/KXmAbBvXTophYGxhUzulqOfWgab.png)![Image Token: S1KRbfaOzoyqNux7uh4laVqVgZc](images/S1KRbfaOzoyqNux7uh4laVqVgZc.png)![Image Token: YMKAbeeLpowghBxfQxmlzfPngAf](images/YMKAbeeLpowghBxfQxmlzfPngAf.png) | + +## 2.1 方舟控制台 + +1. **首次使用签署使用承诺函**：开白用户可见**火山方舟体验中心-视觉模型-视频生成页面顶部【我的素材资产】**，点击进入素材资产管理界面，首次使用前需签署《上传虚拟人像素材合规承诺函》《素材资产功能使用规则》（仅需授权一次） + +![Image Token: ZD36bcZEgo9FXnxm6lvlEX00gqY](images/ZD36bcZEgo9FXnxm6lvlEX00gqY.png) + +![体验中心【我的资产】首次进入时，调起协议弹窗 (Token: EHCSbgUCyocNvdxn4Qql6nHfgab)](images/EHCSbgUCyocNvdxn4Qql6nHfgab.png) + +* **创建素材资产组合（Group）**：可通过控制台上传单个或多个资产文件批量创建素材资产组合（Group），**当前仅支持上传的每个文件分别创建资产组，暂不支持创建一个资产组，同时注入多个资产** + +![【我的素材资产】面板，右上角点击【添加素材资产组】 (Token: HfQvbsOknoJ2MfxVTuVlpKqjg0c)](images/HfQvbsOknoJ2MfxVTuVlpKqjg0c.png) + +![Image Token: H7fabAsJSon7mqx0yzklmB20gXb](images/H7fabAsJSon7mqx0yzklmB20gXb.png) + +![点击上传/拖拽上传文件 (Token: XNrTbx6f9onxK6xzEHmlpPApgNb)](images/XNrTbx6f9onxK6xzEHmlpPApgNb.png) + +* 单次创建上限为**100个资产组合（Group）**，单账号允许的资产组合（Group）数量本期不设限 + +* 单个素材上传要求： + +> - **图片格式**：控制台本期仅支持文件后缀为`.jpg`、`.jpeg`、`.png`（与API有差异） +> +> - **文件大小**：单张图片小于30M +> +> - **宽高比（宽/高）**：(0.4, 2.5) +> +> - **宽高长度（px）**：(300, 6000) + +* 资产组合标题/描述/资产名称字段： + + | **资产组合名称（Group Name）** | 必填，最大字符12（与API有差异） | + | ----------------------------- | ------------------- | + | **资产组合描述（Group Description）** | 选填，最大字符100（与API有差异） | + | **资产名称（Asset Name）** | 必填，最大字符12（与API有差异） | + + ![Image Token: OLX5bqDmuoFvScxMSjoldvMngcg](images/OLX5bqDmuoFvScxMSjoldvMngcg.png) + + * 控制台上传时暂不支持直接编辑上述字段， 支持通过文件命名自动解析 + + > 命名规范：`{AssetName1}&&{GroupName1}&&{GroupDescription1(选填)}.jpg` + > + > 若无`&&`连接符，则文件名=`GroupName`=`AssetName` + + * `GroupName`**或**`GroupDescription`**被审核拦截时，Group会创建失败** + + * 创建完成后支持修改上述字段 + +![资产组合标题、描述修改 (Token: CpDGb1DkHoT0H7xymYXl0fl5gci)](images/CpDGb1DkHoT0H7xymYXl0fl5gci.png) + +![资产名称修改 (Token: FGx3bIe8toKJVixJekllAYmXgsc)](images/FGx3bIe8toKJVixJekllAYmXgsc.png) + + + +* **批量新增素材**：可点击进入某个资产组合（Group），在当前资产组合（Group）下新增资产（Asset） + +![点击某一Group进入详情 (Token: J2bibWD6SoH170xehXWler3ugrg)](images/J2bibWD6SoH170xehXWler3ugrg.png) + +![Image Token: NfxBbdQa9oXQpWxT1GoljirmgXe](images/NfxBbdQa9oXQpWxT1GoljirmgXe.png) + +![点击右上角【添加素材资产】上传Asset (Token: CsgQbFnXOoTJACx2TeZlrQlHgrd)](images/CsgQbFnXOoTJACx2TeZlrQlHgrd.png) + +* 单次新增素材上限为**500个资产**，单账号允许的资产（Asset）数量本期**不设限** + +* 单个素材上传要求： + +> - **图片格式**：控制台本期仅支持文件后缀为`.jpg`、`.jpeg`、`.png`（与API有差异） +> +> - **文件大小**：单张图片小于30M +> +> - **宽高比（宽/高）**：(0.4, 2.5) +> +> - **宽高长度（px）**：(300, 6000) + +* 文件名会自动解析填入AssetName + +| **资产名称（Asset Name）** | 必填，最大字符12（与API有差异） | +| -------------------- | ------------------ | + +* **文件内容或**`AssetName`**被审核拦截时，Asset列表会展示失败状态，有对应报错信息。** + +![报错示意 (Token: Bt9Vbf3ajohV07xVrK1lYKe2gOc)](images/Bt9Vbf3ajohV07xVrK1lYKe2gOc.png) + + + +* **库内资产使用**：可在体验中心界面查看已上传的资产组合（Group）和对应组合下的资产（Asset），一键填入体验中心输入框，或一键复制URI通过API传入 + +![Image Token: Cv3AbbvFHoQuTcxacZclfNfggRc](images/Cv3AbbvFHoQuTcxacZclfNfggRc.png) + +![Image Token: DuDib9l3Ao8NsTx8E0Fl9eQEglb](images/DuDib9l3Ao8NsTx8E0Fl9eQEglb.png) + +![体验中心使用流程示意 (Token: YdKqbTI8fojMc5xAqAElrdOggff)](images/YdKqbTI8fojMc5xAqAElrdOggff.png) + + + +## 2.2 API入库 + +1. **首次使用签署使用承诺函**：通过火山方舟控制台开通管理，点击右上角的【开通素材资产库权限】，勾选同意协议，进行功能开通使用 + +![Image Token: Vvu2bZwhGoTs8MxPc9jlB1rigjh](images/Vvu2bZwhGoTs8MxPc9jlB1rigjh.png) + + + +* **通过Asset API创建、管理素材资产：** + + > **【对客材料】** + > + > * **素材资产库实践手册：**[ 【申请权限填客户名称】私域虚拟人像素材资产库（邀测用户版）](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe) + > + > * **Asset API文档：**[ 【申请权限填客户名称】Asset API 参考文档（邀测用户版）](https://bytedance.larkoffice.com/wiki/FtqVwjinYisraGkT5uncWyd0nEb) diff --git a/docs/API文档/「保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）.md b/docs/API文档/「保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）.md new file mode 100644 index 0000000..4ec7452 --- /dev/null +++ b/docs/API文档/「保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）.md @@ -0,0 +1,314 @@ +# 「⚠️保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版） + +> 本文档仅限预览及邀测用户使用： +> +> * 不承诺正式 API 上线100%一致。 +> +> * 仅限邀测用户阅读，请勿截图/分享给其他人员。 +> +> * 您需确保上传的虚拟人像符合以下条件： +> +> * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。 +> +> * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。 +> +> * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。 + +Seedance 2.0 系列模型具有完备的防范 Deepfake 和侵犯版权风险能力。在生成视频时，会对有风险的参考素材输入进行拦截，最大限度保证生成视频合规和安全性。 + +为确保创作者能充分利用 Seedance 2.0 强大的视频生成能力高效生成视频内容，同时规避 AI 生成内容的潜在风险，方舟推出了私域可信素材库。完成入库的可信素材将进入您的私域素材库，在视频生成中使用。 + +私域素材库使用流程如下： + +![Image Token: CWyVbkJYSoxmeExAhjCcYDOOnPe](images/CWyVbkJYSoxmeExAhjCcYDOOnPe.png) + +## 素材资产库结构说明 + +> 单个素材文件为一个 Asset（素材资产），每个 Asset 属于一个 Group（素材组合）。 +> +> * 可使用素材组自由管理素材。例如，可将同一人物、工作室或项目组的素材放入一个素材组合进行管理。 +> +> * **仅可使用已入库素材的 ID (Asset ID)进行视频生成，同一形象未入库素材无法使用。** +> +> * 仅需入库推理需使用的素材，不需使用的素材请勿入库。 + +以单人物形象为一素材组合为例： + +* 素材资产：一个素材文件（图片），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。 + + * 举例：一张人物装造。 + + * 文件类型：图片 + + > **单张图片要求** + > + > * 格式：jpeg、png、webp、bmp、tiff、gif、heic/heif + > + > * 宽高比（宽/高）： (0.4, 2.5) + > + > * 宽高长度（px）：(300, 6000) + > + > * 大小：单张图片小于 30 MB。 + + * 资产 ID 示例：`asset-20260310035119-h8tq4` + +![Image Token: NfNnbPdRUoLmRdxjoIUcwMvOnAf](images/NfNnbPdRUoLmRdxjoIUcwMvOnAf.png) + +* 素材资产组： + + * 可自由组合素材，以人物、工作室、项目组等维度将素材进行分组管理。 + + * Group ID 示例：`group-20260310035119-*****` + + * 示例： + +![Image Token: E58BbrAcoo1E68xdZPecGDQgn1c](images/E58BbrAcoo1E68xdZPecGDQgn1c.jpeg) + +![Image Token: YX14bprrpoxvgXxHoABczW8EnNb](images/YX14bprrpoxvgXxHoABczW8EnNb.jpeg) + +![Image Token: YoLEbaqR6oic3mx2Ow6cQ1j2nnf](images/YoLEbaqR6oic3mx2Ow6cQ1j2nnf.jpeg) + + + +## 上传素材至私域虚拟人像库 （API & 控制台） + +您可将自有的虚拟形象上传至私域虚拟人像库。 + +> **警告：** +> +> 您需确保上传的虚拟人像符合以下条件： +> +> * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。 +> +> * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。 +> +> * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。 + +方舟将对您上传的素材进行安全审核。审核通过后，即可在体验中心和 API 中使用素材生成视频。 + +您可使用 OpenAPI 或在体验中心上传虚拟素材。 + +### 阅读并同意协议 + +首次入库前，需打开 [控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0\&briefType=introduce\&type=new) > **开通管理** > **开通素材资产库权限，**阅读和同意相关规则和协议： + +![Image Token: ZR4SbE6GColaYKxVTFZcSW1LnFc](images/ZR4SbE6GColaYKxVTFZcSW1LnFc.png) + +先创建 Asset Group, 再向 Group 中添加虚拟人像素材。 + +> 素材格式的具体要求，请参考[素材库结构说明](https://bytedance.larkoffice.com/docx/MpHOdxYbwobmIWxk5rucBLranJb#share-V4mMdM92woylBlxML62c5Aelneh)。 + +### 使用控制台 + +1. 打开 [方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo) > **我的素材资产** > **我的虚拟人像 > 添加虚拟人像**，或左上方 **我的资产**。 + + ![Image Token: VolnbkTKkoQ81kxcksWc3Ts6nDf](images/VolnbkTKkoQ81kxcksWc3Ts6nDf.png) + + ![Image Token: R5wRbFyexonHeRxbIK1cs3ScnAd](images/R5wRbFyexonHeRxbIK1cs3ScnAd.png) + + + +2. 创建素材组合。 + +3. 向素材组合中上传素材。 + +### 使用 API + +先使用 `CreateAssetGroup` API 创建素材组合，再使用 `CreateAsset` API 向组合中上传素材。请求示例： + +1. **创建素材组合** + +> **注意**： +> +> * 调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [API访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。 +> +> * API 参数信息请参考[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/wiki/FtqVwjinYisraGkT5uncWyd0nEb)。 + +使用** POST` `**`CreateAssetGroup` 接口创建素材组合。 + +在请求中传入： + +* **Name**：素材组合的名称。 + +* **Description**: 素材组合的文字描述。 + +* **GroupType**: 选填，默认为 AIGC（虚拟人像素材）。 + +* **ProjectName**：选填，指定资源项目名称，默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考[文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +> **注意** +> +> 如果请求中不指定 **ProjectName**，默认将创建素材组至 **default** 项目中。 + +请求示例： + +**注意**：需使用 AK/SK 鉴权，详情参考 [API访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。 + +返回示例： + +* **上传素材** + +使用 **POST **`CreateAsset`接口上传素材。 + +在请求中提供： + +* **GroupId**：必填，素材组合 ID + +* **URL**: 必填，图片可访问的 URL + +* **AssetType**: 必填，仅支持上传图片类型素材，需指定为 **Image** + +* **Name**: 选填，素材名称，可用于管理素材，如素材文件名。 + +* **ProjectName**：选填，指定资源项目名称，默认为 **default**。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考[文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。 + +> **注意** +> +> 如果请求中不指定 **ProjectName**，则默认上传素材至 **default** 项目中。您需使用该字段确保将素材上传至对应的项目中。 + +**注意**： + +* 每次请求上传一个素材文件。 + +* 该请求返回素材 ID，可使用 GetAsset API 查看是否上传成功。 + +返回示例： + +## 检索虚拟人像资产 （API & 控制台） + +您可使用以下方式检索虚拟人像资产。 + +* **控制台**：您可在 [方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo) >** 我的** > **我的虚拟人像 **中搜索和查看已上传的虚拟人像资产。 + +* **API**： + + * **POST **`GetAsset `获取单个素材 + + * **POST **`ListAssets` 查询素材 + + * **POST **`ListAssetGroups` 查询素材组合信息 + + + +### 获取单个素材信息 + +可使用 **POST **GetAsset 获取单个素材信息，指定素材资产 ID。 + +> **注意**：要获取完整的 API 参数、限流等信息，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。 + +返回示例： + +### 查询素材资产 + +可使用 **POST **ListAssets 查询 Assets。 + +* 支持根据组合 ID (GroupId)、素材状态（Statuses）和素材名称（Name）查询。筛选出符合所有条件的素材。 + +* 支持使用 Name 进行模糊搜索，同时使用 GroupId 精确搜索，便于检索所需的素材。 + +支持使用 SortBy，SortOrder 对结果进行排序 + +> **注意**：获取完整的 API 参考文档，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。 + +返回示例： + +### 查询素材组 + +使用 **POST **ListAssetGroups 查询素材组合信息。 + +支持模糊搜索素材组合名称（Name）或提供多个素材组合（GroupId）。 + +如有多个素材组，可使用 Name 字段进行模糊搜索。 + +> **注意**：要获取完整的 API 参考文档，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。 + +返回示例： + +## 示例：上传素材并使用 GetAsset 获取素材信息 + +以下示例创建素材资产后，查询资产 Status 并根据状态，判断是否继续查询或返回对应结果。 + +代码执行以下逻辑： + +1. createAsset： 上传资源，获取 AssetId + +2. waitForAssetActive：开始查询，循环调用 getAssetStatus 查询当前资产状态 + +3. 根据 Status 判断 + + * Processing → 继续轮询 + + * Active → 返回 URL（结束）状态为 **Active** 后，可使用该素材 Asset ID (URI格式) 进行视频生成，如何使用人像素材生成视频，详见[下文](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-GrbXdVvYjonbMkxQWHEcGf2Inlf)。 + + * Failed → 返回错误（结束） + +4. 返回结果并打印结果 + +查询结果示意如下： + + + +## 使用人像素材生成视频 + +在获取素材 Asset ID后，可使用私域人像素材生成视频。效果预览及使用方式请参考下文。 + +### 效果预览 + +| 输入：文本 | 输入：虚拟人像、图片 | 输出 | +| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | +| **图片1**中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持**图片2**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 | ![Image Token: HX4abuktdoOdZgxrqbxcNBlznSh](images/HX4abuktdoOdZgxrqbxcNBlznSh.png)![Image Token: MHRTb8420oORTqxTohYcrFkRnhc](images/MHRTb8420oORTqxTohYcrFkRnhc.jpeg) | | + +### 视频生成 + +在 Video Generation API 的 **content.<模态>\_url.url** 字段中使用 素材 URI 生成视频。 + +> 资产 URI 拼接方式：`Asset://`** + +具体方式请参考[ 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）](https://bytedance.larkoffice.com/wiki/SANpwJ9bgiKgrykLaMTcAB0InWc#share-ONSwd51ezoXCJqxkAm2cIC61nMX)。 + +示例代码： + +## 常见问题 + +### 1. 为什么素材上传成功后，无法使用素材生成视频或获取素材信息？ + +素材库按**[项目](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)（Project）隔离**。 + +* 在视频生成时，必须使用**素材所在项目**中的推理接入点进行推理。 + +* 如果素材上传成功，但使用获取素材接口获取素材失败，可能是因为调用上传素材(CreateAsset)和获取素材接口时传入了不同的 **ProjectName**。 + + * **ProjectName** 默认值为 `default`，即如果不指定该字段，则默认将资源创建至 `default` 项目中。 + + * 建议在同一个项目中管理素材。 + +### 2. 怎样管理用户对素材库的权限？ + +您可使用[访问控制](https://console.volcengine.com/iam/identitymanage/user) （IAM）精细化管理用户操作素材库的权限。可按以下方式设置： + +1. **创建自定义策略** + + 1. 打开[访问控制](https://console.volcengine.com/iam/policymanage) >** 新建自定义策略** + + 2. 输入策略名称。 + + 3. 切换到 **JSON编辑器**，将下方自定义策略粘贴至编辑器中，点击 **提交** 保存。 + +![Image Token: F0bnb6AanolkCVxjbTdcKMOenkh](images/F0bnb6AanolkCVxjbTdcKMOenkh.png) + +* **为用户/用户组赋权** + + 1. 点击 **用户管理** > **用户**/**用户组**，选择需要赋权的用户或用户组，点击右侧的 **添加权限。** + + 2. 在 **授权策略** 中选择**步骤 1** 中创建的策略。 + + 3. （可选）在 **限制到项目资源 **中选择策略应用的项目。 + + 4. 点击 **提交。** + +完成上述操作后，该用户/用户组即可在对应项目中管理素材。 + +关于 IAM 的更多信息，请参考[访问控制](http://volcengine.com/docs/6257?lang=zh)。 + + + diff --git a/docs/API文档/关于种子值.md b/docs/API文档/关于种子值.md new file mode 100644 index 0000000..2951acd --- /dev/null +++ b/docs/API文档/关于种子值.md @@ -0,0 +1,487 @@ +`POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks` [ ](https://api.volcengine.com/api-explorer/?action=CreateContentsGenerationsTasks&data=%7B%7D&groupName=%E8%A7%86%E9%A2%91%E7%94%9F%E6%88%90API&query=%7B%7D&serviceCode=ark&version=2024-01-01)[运行](https://api.volcengine.com/api-explorer/?action=CreateContentsGenerationsTasks&data=%7B%7D&groupName=%E8%A7%86%E9%A2%91%E7%94%9F%E6%88%90API&query=%7B%7D&serviceCode=ark&version=2024-01-01) +本文介绍创建视频生成任务 API 的输入输出参数，供您使用接口时查阅字段含义。模型会依据传入的图片及文本信息生成视频，待生成完成后，您可以按条件查询任务并获取生成的视频。 +:::warning +Seedance 2.0 模型目前仅支持 [控制台体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128&tab=GenVideo) 在免费额度内体验，暂不支持 API 调用，敬请期待。 + +::: +**不同模型支持的视频生成能力简介** + +* **Seedance 1.5 pro==^new^==** ** ** **==^有声视频^==** **(自定义是否包含音频)** + * 图生视频\-首尾帧，根据您输入的++首帧图片+尾帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。 + * 图生视频\-首帧，根据您输入的++首帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。 + * 文生视频，根据您输入的++文本提示词+参数（可选）++ 生成目标视频。 +* **Seedance 1.0 pro** + * 图生视频\-首尾帧，根据您输入的++首帧图片+尾帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。 + * 图生视频\-首帧，根据您输入的++首帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。 + * 文生视频，根据您输入的++文本提示词+参数（可选）++ 生成目标视频。 +* **Seedance 1.0 pro fast** + * 图生视频\-首帧，根据您输入的++首帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。 + * 文生视频，根据您输入的++文本提示词+参数（可选）++ 生成目标视频。 +* **Seedance 1.0 lite** + * **doubao\-seedance\-1\-0\-lite\-t2v：** 文生视频，根据您输入的++文本提示词+参数（可选）++ 生成目标视频。 + * **doubao\-seedance\-1\-0\-lite\-i2v：** + * 图生视频\-参考图，根据您输入的**++参考图片（1\-4张）++ ** +++文本提示词（可选）+ 参数（可选）++ 生成目标视频。 + * 图生视频\-首尾帧，根据您输入的++首帧图片+尾帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。 + * 图生视频\-首帧，根据您输入的++首帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。 + + +Tips：一键展开折叠，快速检索内容 +打开页面右上角开关，**ctrl ** + **f** 可检索页面内所有内容。 +![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_cae7ddb0e1977b68b353f17897b8574c.png) + + +```mixin-react +return ( + +`}> + +![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2abecd05ca2779567c6d32f0ddc7874d.png =20x) [模型列表](https://www.volcengine.com/docs/82379/1330310?lang=zh#2705b333) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a5fdd3028d35cc512a10bd71b982b6eb.png =20x) [模型计费](https://www.volcengine.com/docs/82379/1544106?redirect=1&lang=zh#02affcb8) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_afbcf38bdec05c05089d5de5c3fd8fc8.png =20x) [API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) + ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_57d0bca8e0d122ab1191b40101b5df75.png =20x) [调用教程](https://www.volcengine.com/docs/82379/1366799) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f45b5cd5863d1eed3bc3c81b9af54407.png =20x) [接口文档](https://www.volcengine.com/docs/82379/1520758) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1609c71a747f84df24be1e6421ce58f0.png =20x) [常见问题](https://www.volcengine.com/docs/82379/1359411) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_bef4bc3de3535ee19d0c5d6c37b0ffdd.png =20x) [开通模型](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false) +`}>); +``` + + +--- + + + +## 请求参数 +> 跳转 [响应参数](#y2hhTyHB) + + +### 请求体 + +--- + + +**model** `string` %%require%% +您需要调用的模型的 ID （Model ID），[开通模型服务](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)，并[查询 Model ID](https://www.volcengine.com/docs/82379/1330310) 。 +您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力，可参考[获取 Endpoint ID](https://www.volcengine.com/docs/82379/1099522)。 + +--- + + +**content** `object[]` %%require%% +输入给模型，生成视频的信息，支持文本、图片和视频（样片，Draft 视频）格式。支持以下几种组合： + +* 文本 +* 文本+图片 +* 视频：其中视频指已成功生成的样片视频，模型可基于样片生成高质量正式视频。 + + +信息类型 + +--- + + +**文本信息** `object` +输入给模型生成视频的内容，文本内容部分。 + +属性 + +--- + + +content.**type ** `string` %%require%% +输入内容的类型，此处应为 `text`。 + +--- + + +content.**text ** `string` %%require%% +输入给模型的文本提示词，描述期望生成的视频。 +支持中英文。建议中文不超过500字，英文不超过1000词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成视频缺失部分元素。提示词的更多使用技巧请参见 [Seedance 提示词指南](https://www.volcengine.com/docs/82379/1587797)。 + + +--- + + +**图片信息** `object` +输入给模型生成视频的内容，图片信息部分。 + +属性 + +--- + + +content.**type ** `string` %%require%% +输入内容的类型，此处应为 `image_url`。支持图片URL或图片 Base64 编码。 + +--- + + +content.**image_url ** `object` %%require%% +输入给模型的图片对象。 + +属性 + +--- + + +content.image_url.**url ** `string` %%require%% +图片信息，可以是图片URL或图片 Base64 编码。 + +* 图片URL：请确保图片URL可被访问。 +* Base64编码：请遵循此格式`data:image/<图片格式>;base64,`，注意 `<图片格式>` 需小写，如 `data:image/png;base64,{base64_image}`。 + +:::tip +传入图片需要满足以下条件： + +* 图片格式：jpeg、png、webp、bmp、tiff、gif。其中，Seedance 1.5 pro 新增支持 heic 和 heif。 +* 宽高比（宽/高）： (0.4, 2.5) +* 宽高长度（px）：(300, 6000) +* 大小：小于 30 MB + +::: + +--- + + +content.**role ** `string` `条件必填` +图片的位置或用途。 +:::warning +首帧图生视频、首尾帧图生视频、参考图生视频为 3 种互斥的场景，不支持混用。 + +::: +图生视频\-首帧 + +* **支持模型：** 所有图生视频模型 +* **字段role取值：** 需要传入1个image_url对象，且字段role可不填，或字段role为：first_frame + + +图生视频\-首尾帧 + +* **支持模型：** Seedance 1.5 pro、Seedance 1.0 pro、Seedance 1.0 lite i2v +* **字段role取值：** 需要传入2个image_url对象，且字段role必填。 + * 首帧图片对应的字段role为：first_frame + * 尾帧图片对应的字段role为：last_frame + +:::tip +传入的首尾帧图片可相同。首尾帧图片的宽高比不一致时，以首帧图片为主，尾帧图片会自动裁剪适配。 + +::: + +图生视频\-参考图 + +* **支持模型：** Seedance 1.0 lite i2v +* **字段role取值：** 需要传入1～4个image_url对象，且字段role必填。 + * 每张参考图片对应的字段role均为：reference_image + +:::tip +参考图生视频功能的文本提示词，可以用自然语言指定多张图片的组合。但若想有更好的指令遵循效果，**推荐使用“[图1]xxx，[图2]xxx”的方式来指定图片**。 +示例1：戴着眼镜穿着蓝色T恤的男生和柯基小狗，坐在草坪上，3D卡通风格 +示例2：[图1]戴着眼镜穿着蓝色T恤的男生和[图2]的柯基小狗，坐在[图3]的草坪上，3D卡通风格 + +::: + + +--- + + +**样片信息==^new^==** ** ** `object` +基于样片任务 ID，生成正式视频。仅 Seedance 1.5 pro 支持该功能。[阅读](https://www.volcengine.com/docs/82379/1366799?lang=zh#5acd28c8)[文档](https://www.volcengine.com/docs/82379/1366799?lang=zh#5acd28c8) 获取 draft 功能的使用教程和注意事项。 + +属性 + +--- + + +content.**type ** `string` %%require%% +输入内容的类型，此处应为 `draft_task`。 + +--- + + +content.**draft_task** ** ** `object` %%require%% +输入给模型的样片任务。 + +属性 + +--- + + +content.draft_task.**id ** `string` %%require%% +样片任务 ID。平台将自动复用 Draft 视频使用的用户输入（**model、** content.**text、** content.**image_url、generate_audio、seed、ratio、duration、camera_fixed ** ），生成正式视频。其余参数支持指定，不指定将使用本模型的默认值。 +使用分为两步：Step1: 调用本接口生成 Draft 视频。Step2: 如果确认 Draft 视频符合预期，可基于 Step1 返回的 Draft 视频任务 ID，调用本接口生成最终视频。[阅读文档](https://www.volcengine.com/docs/82379/1366799?lang=zh#5acd28c8) 获取详细教程。 + + + + +--- + + +**callback_url** `string` +填写本次生成任务结果的回调通知地址。当视频生成任务有状态变化时，方舟将向此地址推送 POST 请求。 +回调请求内容结构与[查询任务API](https://www.volcengine.com/docs/82379/1521309)的返回体一致。 +回调返回的 status 包括以下状态： + +* queued：排队中。 +* running：任务运行中。 +* succeeded： 任务成功。（如发送失败，即5秒内没有接收到成功发送的信息，回调三次） +* failed：任务失败。（如发送失败，即5秒内没有接收到成功发送的信息，回调三次） +* expired：任务超时，即任务处于**运行中或排队中**状态超过过期时间。可通过 **execution_expires_after ** 字段设置过期时间。 + + +--- + + +**return_last_frame** `boolean` `默认值 false` + +* true：返回生成视频的尾帧图像。设置为 `true` 后，可通过 [查询视频生成任务接口](https://www.volcengine.com/docs/82379/1521309) 获取视频的尾帧图像。尾帧图像的格式为 png，宽高像素值与生成的视频保持一致，无水印。 + 使用该参数可实现生成多个连续视频：以上一个生成视频的尾帧作为下一个视频任务的首帧，快速生成多个连续视频，调用示例详见 [教程](https://www.volcengine.com/docs/82379/1366799?lang=zh#141cf7fa)。 +* false：不返回生成视频的尾帧图像。 + + +--- + + +**service_tier** `string` `默认值 default` +> 不支持修改已提交任务的服务等级 + +指定处理本次请求的服务等级类型，枚举值： + +* default：在线推理模式，RPM 和并发数配额较低（详见 [模型列表](https://www.volcengine.com/docs/82379/1330310?lang=zh#2705b333)），适合对推理时效性要求较高的场景。 +* flex：离线推理模式，TPD 配额更高（详见 [模型列表](https://www.volcengine.com/docs/82379/1330310?lang=zh#2705b333)），价格为在线推理的 50%， 适合对推理时延要求不高的场景。 + + +--- + + +**execution_expires_after** ** ** `integer` `默认值 172800` +任务超时阈值。指定任务提交后的过期时间（单位：秒），从 **created at** 时间戳开始计算。默认值 172800 秒，即 48 小时。取值范围：[3600，259200]。 +不论使用哪种 **service_tier**，都建议根据业务场景设置合适的超时时间。超过该时间后任务会被自动终止，并标记为`expired`状态。 + +--- + + +**generate_audio==^new^==** ** ** `boolean` `默认值 true` +> 仅 Seedance 1.5 pro 支持 + +控制生成的视频是否包含与画面同步的声音。 + +* true：模型输出的视频包含同步音频。Seedance 1.5 pro 能够基于文本提示词与视觉内容，自动生成与之匹配的人声、音效及背景音乐。建议将对话部分置于双引号内，以优化音频生成效果。例如：男人叫住女人说：“你记住，以后不可以用手指指月亮。” +* false：模型输出的视频为无声视频。 + + +--- + + +**draft==^new^==** ** ** `boolean` `默认值 false` +> 仅 Seedance 1.5 pro 支持 + +控制是否开启样片模式。[阅读文档](https://www.volcengine.com/docs/82379/1366799?lang=zh#5acd28c8) 获取使用教程和注意事项。 + +* true：开启样片模式，生成一段预览视频，快速验证场景结构、镜头调度、主体动作与 prompt 意图是否符合预期。消耗 token 数较正常视频更少，使用成本更低。 +* false：关闭样片模式，正常生成一段视频。 + +:::tip +开启样片模式后，将使用 480p 分辨率生成 Draft 视频（使用其他分辨率会报错），不支持返回尾帧功能，不支持离线推理功能。 + +::: +--- + + +:::warning 部分参数升级说明 + +* **对于 resolution、ratio、duration、frames、seed、camera_fixed、watermark 参数，平台升级了参数传入方式，示例如下。Seedance 1.0\-1.5 系列模型依然兼容支持旧方式。** +* 不同模型，可能对应支持不同的参数与取值，详见 [输出视频格式](https://www.volcengine.com/docs/82379/1366799?lang=zh#9fe4cce0)。当输入的参数或取值不符合所选的模型时，该参数将被忽略或触发报错： + * 新方式：在 request body 中直接传入参数。此方式为**强校验，** 若参数填写错误，模型会返回错误提示。 + * 旧方式：在文本提示词后追加 \-\-[parameters]。此方式为**弱校验，** 若参数填写错误，模型将自动使用默认值且不会报错。 + + +::: +**新方式（推荐）：在 request body 中直接传入参数** +```JSON +... + // Specify the aspect ratio of the generated video as 16:9, duration as 5 seconds, resolution as 720p, seed as 11, and include a watermark. The camera is not fixed. + "model": "doubao-seedance-1-5-pro-251215", + "content": [ + { + "type": "text", + "text": "小猫对着镜头打哈欠" + } + ], + // All parameters must be written in full; abbreviations are not supported + "resolution": "720p", + "ratio":"16:9", + "duration": 5, + // "frames": 29, Either duration or frames is required + "seed": 11, + "camera_fixed": false, + "watermark": true +... +``` + + + + +**旧方式：在文本提示词后追加 \-\-[parameters]** +```JSON +... + // Specify the aspect ratio of the generated video as 16:9, duration as 5 seconds, resolution as 720p, seed as 11, and include a watermark. The camera is not fixed. + "model": "doubao-seedance-1-5-pro-251215", + "content": [ + { + "type": "text", + "text": "小猫对着镜头打哈欠 --rs 720p --rt 16:9 --dur 5 --seed 11 --cf false --wm true" + // "text": "小猫对着镜头打哈欠 --resolution 720p --ratio 16:9 --duration 5 --seed 11 --camerafixed false --watermark true" + } + ] +... +``` + + + + +--- + + +**resolution ** `string` +> Seedance 1.5 pro、Seedance 1.0 lite 默认值：`720p` +> Seedance 1.0 pro & pro\-fast 默认值：`1080p` + +视频分辨率，枚举值： + +* 480p +* 720p +* 1080p：参考图场景不支持 + + +--- + + +**ratio ** `string` +> 文生视频：默认值 `16:9`（ Seedance 1.5 Pro 默认值为 `adaptive`） +> 图生视频：默认值 `adaptive`（参考图生视频场景默认值为 `16:9`） + +生成视频的宽高比例。不同宽高比对应的宽高像素值见下方表格。 + +* 16:9 +* 4:3 +* 1:1 +* 3:4 +* 9:16 +* 21:9 +* adaptive：根据输入自动选择最合适的宽高比（详见下文说明） + +:::warning **adaptive ** 适配规则 +当配置 **ratio** 为 `adaptive` 时，模型会根据生成场景自动适配宽高比；实际生成的视频宽高比可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **ratio** 字段获取。 + +* 文生视频场景：根据输入的提示词，自动选择最合适的宽高比（仅 Seedance 1.5 Pro 支持）。 +* 图生视频场景： + * 参考图生视频：不支持配置 **ratio** 为 `adaptive`。 + * 首帧 / 首尾帧生视频：根据上传的首帧图片比例，自动选择最合适的宽高比。 + + +::: +**不同宽高比对应的宽高像素值** +Note：图生视频，选择的宽高比与您上传的图片宽高比不一致时，方舟会对您的图片进行裁剪，裁剪时会居中裁剪，详细规则见 [图片裁剪规则](https://www.volcengine.com/docs/82379/1366799?lang=zh#f76aafc8)。 + +|分辨率 |宽高比|宽高像素值|宽高像素值|\ +| | |Seedance 1.0 系列 |Seedance 1.5 pro | +|---|---|---|---| +|480p |16:9 |864×480 |864×496 | +|^^|4:3 |736×544 |752×560 | +|^^|1:1 |640×640 |640×640 | +|^^|3:4 |544×736 |560×752 | +|^^|9:16 |480×864 |496×864 | +|^^|21:9 |960×416 |992×432 | +|720p |16:9 |1248×704 |1280×720 | +|^^|4:3 |1120×832 |1112×834 | +|^^|1:1 |960×960 |960×960 | +|^^|3:4 |832×1120 |834×1112 | +|^^|9:16 |704×1248 |720×1280 | +|^^|21:9 |1504×640 |1470×630 | +|1080p |16:9 |1920×1088 |1920×1080 |\ +|> 1.0 lite 参考图场景不支持 | | | | +|^^|4:3 |1664×1248 |1664×1248 | +|^^|1:1 |1440×1440 |1440×1440 | +|^^|3:4 |1248×1664 |1248×1664 | +|^^|9:16 |1088×1920 |1080×1920 | +|^^|21:9 |2176×928 |2206×946 | + + + + +--- + + +**duration** `integer` `默认值 5` +> duration 和 frames 二选一即可，frames 的优先级高于 duration。如果您希望生成整数秒的视频，建议指定 duration。 + +生成视频时长，单位：秒。支持 2~12 秒。 +:::warning +Seedance 1.5 pro 支持两种配置方法 + + * 指定具体时长：支持 [4,12] 范围内的任一整数。 + * 不指定具体生成时长：设置为 `-1`，表示由模型在 [4,12] 范围内自主选择合适的视频长度（整数秒）。实际生成视频的时长可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **duration** 字段获取。注意视频时长与计费相关，请谨慎设置。 + + +::: +--- + + +**frames** `integer` +> Seedance 1.5 pro 暂不支持 +> duration 和 frames 二选一即可，frames 的优先级高于 duration。如果您希望生成小数秒的视频，建议指定 frames。 + +生成视频的帧数。通过指定帧数，可以灵活控制生成视频的长度，生成小数秒的视频。 +由于 frames 的取值限制，仅能支持有限小数秒，您需要根据公式推算最接近的帧数。 + +* 计算公式：帧数 = 时长 × 帧率（24）。 +* 取值范围：支持 [29, 289] 区间内所有满足 `25 + 4n` 格式的整数值，其中 n 为正整数。 + +例如：假设需要生成 2.4 秒的视频，帧数=2.4×24=57.6。由于 frames 不支持 57.6，此时您只能选择一个最接近的值。根据 25+4n 计算出最接近的帧数为 57，实际生成的视频为 57/24=2.375 秒。 + +--- + + +**seed** `integer` `默认值 -1` +种子整数，用于控制生成内容的随机性。 +取值范围：[\-1, 2^32\-1]之间的整数。 +:::warning + +* 相同的请求下，模型收到不同的seed值，如：不指定seed值或令seed取值为\-1（会使用随机数替代）、或手动变更seed值，将生成不同的结果。 +* 相同的请求下，模型收到相同的seed值，会生成类似的结果，但不保证完全一致。 + + +::: +--- + + +**camera_fixed** `boolean` `默认值 false` +> 参考图场景不支持 + +是否固定摄像头。枚举值： + +* true：固定摄像头。平台会在用户提示词中追加固定摄像头，实际效果不保证。 +* false：不固定摄像头。 + + +--- + + +**watermark** `boolean` `默认值 false` +生成视频是否包含水印。枚举值： + +* false：不含水印。 +* true：含有水印。 + + +--- + + + +## 响应参数 +> 跳转 [请求参数](#RxN8G2nH) + +**id ** `string` +视频生成任务 ID 。仅保存 7 天（从 **created at** 时间戳开始计算），超时后将自动清除。 + +* 设置`"draft": true`，为 Draft 视频任务 ID。 +* 设置 `"draft": false`，为正常视频任务 ID。 + +创建视频生成任务为异步接口，获取 ID 后，需要通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309) 来查询视频生成任务的状态。任务成功后，会输出生成视频的`video_url`。 + + diff --git a/docs/API文档/推理节点.md b/docs/API文档/推理节点.md new file mode 100644 index 0000000..194284a --- /dev/null +++ b/docs/API文档/推理节点.md @@ -0,0 +1,1074 @@ +数分钟内完成你的首次 API 调用。 + + + + + + + +**快速入门(新手版)** +专为零基础用户设计的快速入门 + + + + + + + + + + + + +**体验中心** +“0”代码，交互式体验模型能力 + + + + + + + + + + + + +**Coding Plan** +兼容主流 AI 编码工具，助力高效编码开发 + + + + + + + + + + +# 1 获取并配置 API Key + +1. 获取 API Key：访问[API Key 管理](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey) ，创建你的 API Key。 +2. 配置环境变量：在终端中运行下面命令（替换`your_api_key_here` 为你的方舟API Key），配置 API Key 到环境变量。 +> 配置持久化环境变量方法参见 [环境变量配置指南](/docs/82379/1820161)。 + + +```mixin-react +return ( + + + +); +``` + + + +# 2 开通模型服务 +访问 [开通管理页面](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement) 开通模型服务。 + +# 3 安装 SDK +安装官方或三方 SDK。 + +```mixin-react +return ( + 运行环境中需安装 [Python](https://www.python.org/downloads/) 版本 3.7 或以上。 + +* 安装方舟 SDK： + \`\`\`Bash + pip install 'volcengine-python-sdk[ark]' + \`\`\` + +* 安装 OpenAI SDK： + \`\`\`Bash + pip install openai + \`\`\` + +`}> + 环境中安装 [Go](https://golang.google.cn/doc/install) 版本 1.18 或以上。 + +在代码中通过下方方法引入 Go SDK +\`\`\`Go +import ( + "github.com/volcengine/volcengine-go-sdk" +) +\`\`\` + +`}> + 环境中安装 [Java](https://www.java.com/en/download/help/index_installing.html) 版本 1.8 或以上。 + +在项目的\`pom.xml\`文件中添加以下依赖配置。 +\`\`\`XML + + com.volcengine + volcengine-java-sdk-ark-runtime + LATEST + +\`\`\` + +`}>); +``` + + +# 4 发起 API 请求 +以下按输入输出类别列举的典型任务，选择任意示例代码体验如何通过 API 调用及体验大模型及方舟平台能力。 + +## 文本生成 +传入文本类信息给模型，进行问答、分析、改写、摘要、编程、翻译等任务，并返回文本结果。 + + +|输入 |输出预览 | +|---|---| +|Hello |* 思考：Got it, let's see. The user said "hello". I need to respond in a friendly and welcoming way. Since the system prompt mentions a professional but friendly tone, I should keep it natural. Maybe something like "Hello! How can I assist you today?" That's simple, polite, and open\-ended to encourage the user to share what they need help with.|\ +| |* 回答：Hello! How can I assist you today? Whether you have a question, need help with something specific, or just want to chat, feel free to let me know. 😊 | + + +```mixin-react +return ( + + + + +); +``` + + +* [文本生成](/docs/82379/1399009)：文本生成使用指南。 +* [深度思考](/docs/82379/1956279)：深度思考能力使用指南。 +* [迁移至 Responses API](/docs/82379/1585128)：新用户推荐，更简洁的上下文管理能力、强大的工具调用能力。 +* [Chat API](https://www.volcengine.com/docs/82379/1494384)：存量业务迭代推荐，广泛使用的 API。 + + +## 多模态理解 +传入图片、视频、PDF文件给模型，进行分析、内容审核、问答、视觉定位等基于多模态理解相关任务，并返回文本结果。 + + +|输入 |输出预览 | +|---|---| +|![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a31c2edfbe844461a43f5e8f74fbcce4~tplv-goo7wpa0wc-image.image =275x) |* 思考：用户现在需要找支持输入图片的模型系列，看表格里的输入列中的图像列，哪个模型对应的图像输入是√。看表格，Doubao\-1.5\-vision那一行的输入图像列是√，其他两个Doubao\-1.5\-pro和lite的输入图像都是×，所以答案是Doubao\-1.5\-vision。|\ +|> 支持输入图片的模型系列是哪个？ |* 回答：支持输入图片的模型系列是Doubao\-1.5\-vision | + + +```mixin-react +return ( + + + + +); +``` + + +* [多模态理解](/docs/82379/1958521)：多模态理解详细使用指南。 +* [视觉定位 Grounding](/docs/82379/1616136)：图片中找到对应目标并返回坐标任务。 +* [GUI 任务处理](/docs/82379/1584296)：在计算机/移动设备中完成自动化任务。 +* [文件输入(File API)](/docs/82379/1885708)：传入图片、视频、文档接口。 + + +## 图片生成 +传入图片、文字给模型，进行以下场景&任务： + +* 广告、海报、组图等图片生成； +* 增改元素、颜色更换等图片编辑； +* 油墨、水墨等风格切换。 + + + +|提示词 |输出预览 | +|---|---| +|充满活力的特写编辑肖像，模特眼神犀利，头戴雕塑感帽子，色彩拼接丰富，眼部焦点锐利，景深较浅，具有Vogue杂志封面的美学风格，采用中画幅拍摄，工作室灯光效果强烈。 |![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/00fb66006eb84b16965b620b6e1f2d78~tplv-goo7wpa0wc-image.image =275x) | + + +```mixin-react +return ( + + + + +); +``` + + +* [Seedream 4.0-5.0 教程](/docs/82379/1824121)：主流生图模型能力以及如何通过 API 调用。 +* [Seedream 4.0-4.5 提示词指南](/docs/82379/1829186)：使用生图模型时，如何编写提示词。 + + +## 视频生成 +通过文本描述、图像素材、视频素材，快速生成高质量、风格多样的视频内容。 + + +|提示词 |输出画面预览 | +|---|---| +|一位身穿绿色亮片礼服的女性站在粉红色背景前，周围飘落着五彩斑斓的彩纸 |![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/aae3d0c636954bdd9e66e7a23e98c480~tplv-goo7wpa0wc-image.image =275x) | + + +```mixin-react +return ( + + contents = new ArrayList<>(); + contents.add(Content.builder() + .type("text") + .text("一位身穿绿色亮片礼服的女性站在粉红色背景前，周围飘落着五彩斑斓的彩纸 --wm true --dur 5") + .build()); + + // Create a video generation task + CreateContentGenerationTaskRequest createRequest = CreateContentGenerationTaskRequest.builder() + .model("doubao-seedance-2-0-260128") // Replace with Model ID + .content(contents) + .build(); + + CreateContentGenerationTaskResult createResult = service.createContentGenerationTask(createRequest); + System.out.println(createResult); + + // Get the details of the task + String taskId = createResult.getId(); + GetContentGenerationTaskRequest getRequest = GetContentGenerationTaskRequest.builder() + .taskId(taskId) + .build(); + + System.out.println("----- polling task status -----"); + while (true) { + try { + GetContentGenerationTaskResponse getResponse = service.getContentGenerationTask(getRequest); + String status = getResponse.getStatus(); + if ("succeeded".equalsIgnoreCase(status)) { + System.out.println("----- task succeeded -----"); + System.out.println(getResponse); + service.shutdownExecutor(); + break; + } else if ("failed".equalsIgnoreCase(status)) { + System.out.println("----- task failed -----"); + System.out.println("Error: " + getResponse.getStatus()); + service.shutdownExecutor(); + break; + } else { + System.out.printf("Current status: %s, Retrying in 3 seconds...\\n", status); + TimeUnit.SECONDS.sleep(3); + } + } catch (InterruptedException ie) { + Thread.currentThread().interrupt(); + System.err.println("Polling interrupted"); + service.shutdownExecutor(); + break; + } + } + } +} +\`\`\` + +`}> +); +``` + + +* [视频生成](/docs/82379/1366799)：学习如何使用模型的视频生成能力，包括文本生成视频、首尾帧生视频、首帧生成视频等。 +* [Seedance-1.0-pro&pro-fast 提示词指南](/docs/82379/1631633)：使用生视频模型时，如何编写提示词。 + + +## 工具使用 +通过工具/插件让模型具体读取外部数据及函数的能力，包括 + +* 内置工具：联网搜索、图片处理、知识库检索等已集成至方舟平台的工具。 +* 三方工具：兼容MCP 的三方工具。 +* 自定义工具：您自行定义及开发的工具。 + + + +|输入 |输出预览 | +|---|---| +|What's the weather like in Beijing? |According to the latest weather data as of March 10, 2026, the current weather in Beijing is sunny with a gentle wind (less than level 3). The temperature around 11:30 AM is approximately 9°C, and it is expected to reach a high of 12°C during the day. The weather will remain clear at night with a low temperature of 1°C.|\ +| |**Source**: Weather forecasts updated on March 10, 2026, from the Central Meteorological Observatory.|\ +| |**Note: Data is accurate as of the latest available update at 05:30 AM on March 10.** | + + +```mixin-react +return ( + + + buildTools() { + ToolWebSearch t = ToolWebSearch.builder().build(); + System.out.println(Arrays.asList(t)); + return Arrays.asList(t); + } + + public static void main(String[] args) throws JsonProcessingException { + String apiKey = System.getenv("ARK_API_KEY"); + + ArkService arkService = ArkService.builder().apiKey(apiKey).baseUrl("https://ark.cn-beijing.volces.com/api/v3").build(); + CreateResponsesRequest req = CreateResponsesRequest.builder() + .model("doubao-seed-2-0-lite-260215") + .input(ResponsesInput.builder().addListItem( + ItemEasyMessage.builder().role(ResponsesConstants.MESSAGE_ROLE_USER).content( + MessageContent.builder() + .addListItem(InputContentItemText.builder().text("What's the weather like in Beijing?").build()) + .build() + ).build() + ).build()) + .tools(buildTools()) + .build(); + ResponseObject resp = arkService.createResponse(req); + System.out.println(resp); + + arkService.shutdownExecutor(); + } +} +\`\`\` + +`}> + +); +``` + + +* [工具调用](/docs/82379/1958524)：学习如何让模型使用内置工具，如网页搜索、知识库检索、豆包助手等能力。 +* [函数调用 Function Calling](/docs/82379/1262342)：学习如何让模型调用自定义的工具。 +* [云部署 MCP / Remote MCP](/docs/82379/1827534)：学习如何让模型使用 MCP 服务。 + + +# 5 下一步 +现在你已经完成了首次方舟模型服务的 API 调用，你可以探索模型的更多能力，包括： + +* [平台能力速览](/docs/82379/1108216)：探索方舟平台提供的提示词优化、权限管理、模型管理等高阶能力。 +* [模型列表](/docs/82379/1330310)：快速浏览方舟提供的模型全集以及各个模型所具备的能力，快速根据你的实际场景匹配到合适的模型。 + + +