Seedance 视频（2.0、2.5）生成相关接口（含素材库）
gpulink MaaS 为客户提供 Seedance 2.0 / Seedance 2.0 Fast /Seedance 2.5 接入能力。本文档面向接入 gpulink MaaS 的开发者，涵盖所有生成模式、素材管理、鉴权、计费规则和错误处理。
一、产品概述
Seedance 2.0 是一款多模态视频生成模型，支持以下生成模式：
生成模式
输入
典型应用
文生视频
纯文本
创意短片、广告、概念验证
首帧图生视频
文本 + 首帧图
从静态画面延展动态场景
首尾帧生视频
文本 + 首帧图 + 尾帧图
明确起始与结束的镜头切换
参考图生视频
文本 + N 张参考图
角色/场景一致性控制
视频延续
文本 + 源视频
扩展已有视频片段的时长或风格
视频编辑
文本 + 源视频 + 参考图
替换视频中的物体、保留原机位
多模态合成
文本 + 图 + 视频 + 音频
带背景音乐/音效的完整视频
二、快速开始
2.1 鉴权
所有接口统一使用 Bearer Token：
4
Authorization: Bearer <API_KEY>
Content-Type: application/json

Token 权限范围由"模型"控制，一个 Token 可能同时拥有多个模型的访问权。任务查询/下载接口使用和任务提交相同的 Token。
2.2 环境与 Base URL
gpulink MaaS 提供两套环境，接入路径完全相同，请根据阶段选择：
环境
Base URL
用途
生产环境
﻿https://api-model.gpulink.cc/v1\﻿
正式业务流量
测试环境
﻿https://api-model-test.gpulink.cc/v1\﻿
接入调试、回归验证
各接口的完整路径（所有示例中 BASE_URL 均指上表中的任一环境）：
接口类别
基础路径
说明
素材管理
﻿{BASE_URL}/seedance/asset/﻿
﻿CreateAssetGroup / CreateAsset / GetAsset 等动作接在该路径后
视频生成
﻿{BASE_URL}/video/generations﻿
提交任务、查询任务状态
提示：生产环境和测试环境的账号体系、API Key、素材数据相互隔离，测试环境创建的素材在生产环境不可见，反之亦然。
2.3 第一次调用（素材库管理）
12
# 生产环境
BASE_URL="https://api-model.gpulink.cc/v1"
# 测试环境（调试时使用）
# BASE_URL="https://api-model-test.gpulink.cc/v1"
API_KEY="sk-your-api-key-here"

curl -X POST "$BASE_URL/seedance/asset/CreateAssetGroup" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name": "广告素材组", "Description": "Q2 产品广告参考素材"}'

返回：
7
{
  "state": 1,
  "data": { "Id": "group-20260412163933-zwxdc" },
  "error": null
}

后续可调用 CreateAsset / GetAsset 完成素材上传与状态轮询，见第三节。
2.4 第一次调用（视频任务）
支持的模型：
模型名
描述
适用场景
﻿doubao-seedance-2-0-260128﻿
Seedance 2.0 标准版
追求最佳画质、复杂镜头调度
﻿doubao-seedance-2-0-fast-260128﻿
Seedance 2.0 Fast
追求低延迟、成本敏感的场景
两个模型的请求格式完全一致，可直接替换 model 字段。
16
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "A cinematic short clip of a corgi running on a beach"}
    ],
    "metadata": {
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9"
    }
  }'

返回：
3
{ "task_id": "cgt-20260412163502-x8k2m" }

后续用 GET /video/generations/{task_id} 轮询任务状态即可，见第四节。
三、素材管理接口（含真人）
对于需要多次复用、需要预审、或来自非公网 URL 的素材，推荐先通过素材管理接口上传，再在视频生成时引用素材 ID。素材数据按账号隔离，无法跨账号访问。
素材管理接口的基础路径为 {BASE_URL}/seedance/asset/，后接具体动作名称。例如完整的创建素材组接口为：
5
BASE_URL=https://api-model.gpulink.cc/v1            (生产)
BASE_URL=https://api-model-test.gpulink.cc/v1       (测试)
{BASE_URL}/seedance/asset/CreateAssetGroup

3.1 典型使用流程
6
1. CreateAssetGroup  → 拿到 GroupId
2. CreateAsset       → 绑定 GroupId + 素材 URL → 拿到 AssetId
3. GetAsset（轮询）  → 等待 Status 变为 Active
4. 在视频生成请求中使用素材引用（推荐）：asset://{assetId}

3.2  创建素材组
3.2.1 CreateAssetGroup —非真人素材素材组创建
3
POST {BASE_URL}/seedance/asset/CreateAssetGroup

请求体：
字段
类型
必填
说明
﻿Name﻿
string
是
素材组名称，≤ 64 字符
﻿Description﻿
string
否
素材组描述，≤ 300 字符
示例：
6
curl -X POST "$BASE_URL/seedance/asset/CreateAssetGroup" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name": "广告素材组", "Description": "Q2 产品广告参考素材"}'

响应：
7
{
  "state": 1,
  "data": { "Id": "group-20260412163933-zwxdc" },
  "error": null
}

错误响应示例：
9
{
  "error": {
    "code": "InvalidParameter",
    "message": "Name is required",
    "type": "new_api_error"
  }
}

3.2.2 CreateRealPersonAuthSession-真人素材素材组创建
3
POST {BASE_URL}/seedance/asset/CreateRealPersonAuthSession

请求示例：
5
 curl -X POST "$BASE_URL/v1/seedance/asset/CreateRealPersonAuthSession" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
响应：
11
{
    "requestId": "869ff4a2-bbb8-41da-a2db-5ccc41daca15",
    "code": 0,
    "message": "success",
    "data": {
        "bytedToken": "202608311102565EC690FA224CAE2900BB",
        "h5Link": "https://ark.volcengine.com/region:cn-beijing/mobile/livenees-face-manage/authorization?pl=xxx",
        "expiresIn": 120
    }
}
      获取响应的h5链接地址之后在手机端浏览器打开网站，在120秒内进行真人验证后拿到真人素材组的groupId，拿到真人素材库id之后上次素材（接口见3.3），素材的图片必须与真人一致，否则用生成的素材生成视频时候会提示不一致情况。
﻿
3.3 CreateAsset — 上传素材
3
POST {BASE_URL}/seedance/asset/CreateAsset

重点：CreateAsset 的 URL 字段用于把你的原始素材导入素材库（通常是公网 HTTPS 地址，供服务端拉取并审核/转码）。  
导入成功后你会拿到 AssetId，在后续的视频生成请求里，image_url.url / video_url.url / audio_url.url 推荐直接写 asset://{assetId} 来引用素材库资产（而不是再去填你自己的公网 URL）。
请求体：
字段
类型
必填
说明
﻿GroupId﻿
string
是
目标素材组 ID（必须是当前账号创建的）
﻿URL﻿
string
是
素材的公网可访问地址（用于导入素材库）
﻿AssetType﻿
string
是
﻿Image / Video / Audio﻿
﻿Name﻿
string
否
素材名称，≤ 64 字符
示例：
11
curl -X POST "$BASE_URL/seedance/asset/CreateAsset" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260412163933-zwxdc",
    "URL": "https://your-cdn.example.com/reference.jpg",
    "AssetType": "Image",
    "Name": "主角参考图"
  }'

响应：
7
{
  "state": 1,
  "data": { "Id": "asset-20260412163936-ftv7n" },
  "error": null
}

错误响应示例（HTTP 200，业务失败）：
14
{
  "state": 1,
  "data": {
    "Id": "asset-20260412163936-ftv7n",
    "Status": "Failed",
    "Error": {
      "Code": "InvalidParameter.AssetProcessFailed",
      "Message": "asset process failed"
    }
  },
  "error": null
}

错误响应示例（HTTP 400）：
9
{
  "error": {
    "code": "InvalidParameter",
    "message": "URL is invalid or unreachable",
    "type": "new_api_error"
  }
}

3.4 GetAsset — 查询素材
3
POST {BASE_URL}/seedance/asset/GetAsset

请求体：
字段
类型
必填
说明
﻿Id﻿
string
是
素材 ID
示例：
6
curl -X POST "$BASE_URL/seedance/asset/GetAsset" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id": "asset-20260412163936-ftv7n"}'

响应：
17
{
  "state": 1,
  "data": {
    "Id": "asset-20260412163936-ftv7n",
    "Name": "主角参考图",
    "URL": "https://processed-cdn-url/reference.jpg?signed=...",
    "AssetType": "Image",
    "GroupId": "group-20260412163933-zwxdc",
    "Status": "Active",
    "CreateTime": "2026-04-12T08:39:36Z",
    "UpdateTime": "2026-04-12T08:39:51Z",
    "Error": null
  },
  "error": null
}

错误响应示例（HTTP 200，业务失败）：
14
{
  "state": 1,
  "data": {
    "Id": "asset-20260412163936-ftv7n",
    "Status": "Failed",
    "Error": {
      "Code": "InvalidParameter.AssetProcessFailed",
      "Message": "asset process failed"
    }
  },
  "error": null
}

错误响应示例（HTTP 404）：
9
{
  "error": {
    "code": "NotFound",
    "message": "asset not found",
    "type": "new_api_error"
  }
}

素材 Status 状态：
状态
含义
建议
﻿Processing﻿
正在审核与处理
继续轮询
﻿Active﻿
审核通过，可用于视频生成
使用返回的 URL﻿
﻿Failed﻿
审核失败
查看 Error 字段，换素材重试
轮询建议：5–15 秒间隔，图片通常 < 30 秒完成，视频/音频稍长。
四、视频任务接口
4.1 提交视频任务
4.1.1 接口定义
5
POST {BASE_URL}/video/generations
Authorization: Bearer <API_KEY>
Content-Type: application/json

其中 BASE_URL 为 https://api-model.gpulink.cc/v1\（生产）或 https://api-model-test.gpulink.cc/v1\（测试）。下文所有示例同。
4.1.2 请求体顶层字段
字段
类型
必填
说明
﻿model﻿
string
是
模型名，见 2.4﻿
﻿content﻿
array
是
多模态输入数组，顺序决定角色分配
﻿metadata﻿
object
否
生成参数扩展区，见 4.1.5
4.1.3 content 数组元素类型
每个元素是一个对象，type 字段指定类型：
﻿type﻿
子字段
说明
﻿text﻿
﻿text﻿
提示词，建议放在数组首位
﻿image_url﻿
﻿image_url.url + role﻿
引用图片素材（推荐：asset://{assetId}）
﻿video_url﻿
﻿video_url.url + role﻿
引用视频素材（推荐：asset://{assetId}）
﻿audio_url﻿
﻿audio_url.url + role﻿
引用音频素材（推荐：asset://{assetId}）
﻿draft_task﻿
﻿draft_task.id﻿
引用草稿任务（不可与其它类型混用）
4.1.4 role 取值与语义
媒体类型
﻿role﻿
含义
图片
﻿first_frame﻿
作为视频的第一帧
图片
﻿last_frame﻿
作为视频的最后一帧
图片
﻿reference_image﻿
提供角色/物体/场景的视觉参考
视频
﻿reference_video﻿
作为延续或编辑的源视频
音频
﻿reference_audio﻿
作为视频的背景音乐或音效
混用规则（违反会返回 400）：
●﻿reference_image 不能与 first_frame / last_frame 同时出现
●﻿audio_url 必须至少搭配一个图片或视频输入，不能单独作为唯一输入
●﻿draft_task 必须是 content 数组里的唯一元素
4.1.5 metadata 支持字段
字段
类型
默认
说明
﻿duration﻿
int
5
视频时长（秒），Seedance 2.0 合法范围 [4, 15] 、Seedance 2.5 合法范围 [4, 30]或 -1（模型自动决定）
﻿resolution﻿
string
﻿720p﻿
分辨率：480p / 720p / 1080p﻿
﻿ratio﻿
string
﻿16:9﻿
宽高比：16:9 / 9:16 / 1:1 / 4:3 / adaptive﻿
﻿frames﻿
int
-
视频总帧数，与 duration 二选一，frames 优先
﻿seed﻿
int
随机
控制生成随机性，相同 seed + 相同输入得到相近结果
﻿camera_fixed﻿
bool
false
是否固定机位（抑制镜头运动）
﻿watermark﻿
bool
true
是否在视频右下角加水印
﻿generate_audio﻿
bool
false
是否生成或合成音频（使用 reference_audio 时必须设为 true）
﻿tools﻿
array
-
工具扩展参数（透传）
﻿safety_identifier﻿
string
-
安全标识（透传）
﻿image_mode﻿
string
-
图像模式参数（透传）
﻿return_last_frame﻿
bool
false
返回末帧图片 URL，便于后续续写
﻿draft﻿
bool
false
草稿模式（生成速度更快、质量略低，用于预览）
﻿service_tier﻿
string
﻿default﻿
服务等级
﻿execution_expires_after﻿
int
172800
任务最长执行时间（秒），范围 [3600, 259200]，即 1 小时到 3 天
﻿callback_url﻿
string
-
任务完成时的回调 URL
4.1.6 响应（成功 / 错误）
成功响应（HTTP 200）：
3
{ "task_id": "cgt-20260412163502-x8k2m" }

﻿task_id 是后续查询任务状态的唯一凭证，请保存。
错误响应示例（HTTP 4xx / 5xx）：
9
{
  "error": {
    "code": "InvalidParameter",
    "message": "the parameter duration specified in the request is not valid",
    "type": "new_api_error"
  }
}

4.1.7 提交示例（生成模式）
以下示例统一使用：
●﻿BASE_URL=https://api-model.gpulink.cc/v1\﻿
●﻿API_KEY=sk-your-api-key-here﻿
4.1.7.1 文生视频
16
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "A serene lake at sunrise, gentle ripples on the water, cinematic"}
    ],
    "metadata": {
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9"
    }
  }'

4.1.7.2 首帧图生视频
13
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "Animate naturally from the first frame, camera slowly moves forward"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "first_frame"}
    ],
    "metadata": {"duration": 10, "resolution": "720p", "ratio": "adaptive"}
  }'

4.1.7.3 首尾帧生视频
14
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "Smooth transition from first frame to last frame"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "last_frame"}
    ],
    "metadata": {"duration": 5, "resolution": "720p", "ratio": "16:9"}
  }'

4.1.7.4 参考图生视频（单图）
13
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "The subject walks forward naturally"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "reference_image"}
    ],
    "metadata": {"duration": 10, "resolution": "720p", "ratio": "16:9"}
  }'

4.1.7.5 参考图生视频（多图）
用于保持角色一致性的场景，例如两个人物的互动：
14
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "图1和图2中的两个人物在森林中奔跑，自然光线，电影质感"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "reference_image"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "reference_image"}
    ],
    "metadata": {"duration": 8, "resolution": "720p", "ratio": "16:9"}
  }'

4.1.7.6 视频续写
从已有视频延伸生成：
13
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "Continue the motion and style of the source video"},
      {"type": "video_url", "video_url": {"url": "asset://{assetId}"}, "role": "reference_video"}
    ],
    "metadata": {"duration": 8, "resolution": "720p", "ratio": "adaptive"}
  }'

4.1.7.7 视频编辑
保留源视频的运镜，替换其中的物体：
14
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "Replace product in video with product in image, keep camera motion"},
      {"type": "video_url", "video_url": {"url": "asset://{assetId}"}, "role": "reference_video"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "reference_image"}
    ],
    "metadata": {"duration": 8, "resolution": "720p", "ratio": "16:9", "return_last_frame": true}
  }'

4.1.7.8 多模态生视频（图 + 视频 + 音频）
完整的广告合成场景：
22
curl -X POST "$BASE_URL/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "第一人称视角果茶广告：0-2秒 手摘苹果；2-4秒 切镜头投入雪克杯摇晃；4-6秒 倒入透明杯特写；6-8秒 举杯到镜头前"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "reference_image"},
      {"type": "image_url", "image_url": {"url": "asset://{assetId}"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "asset://{assetId}"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "asset://{assetId}"}, "role": "reference_audio"}
    ],
    "metadata": {
      "duration": 8,
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false
    }
  }'

重要：使用 reference_audio 时必须同时设置 generate_audio: true，否则音频不会被合成到最终视频。参见第五节约束说明。
4.2 查询视频任务
4.2.1 接口定义
4
GET {BASE_URL}/video/generations/{task_id}
Authorization: Bearer <API_KEY>

4.2.2 响应（成功 / 错误）
成功响应（HTTP 200）：
26
{
  "code": "success",
  "data": {
    "task_id": "cgt-20260412163502-x8k2m",
    "status": "SUCCESS",
    "progress": "100%",
    "submit_time": 1775908082,
    "start_time": 1775908086,
    "finish_time": 1775908321,
    "data": {
      "status": "succeeded",
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9",
      "content": {
        "video_url": "https://example.com/video/cgt-20260412163502-x8k2m.mp4?signature=\*\*\*"
      },
      "usage": {
        "completion_tokens": 108900,
        "total_tokens": 108900
      }
    }
  }
}

错误响应示例（HTTP 200，业务失败）：
14
{
  "code": "success",
  "data": {
    "task_id": "cgt-20260412163502-x8k2m",
    "status": "FAILURE",
    "progress": "100%",
    "fail_reason": "content safety check failed",
    "data": {
      "status": "failed"
    }
  }
}

错误响应示例（HTTP 404）：
9
{
  "error": {
    "code": "NotFound",
    "message": "task_id not found",
    "type": "new_api_error"
  }
}

4.2.3 任务状态字段
﻿data.status 外层状态（建议使用）：
值
含义
﻿SUBMITTED﻿
任务已提交，尚未开始
﻿IN_PROGRESS﻿
正在生成
﻿SUCCESS﻿
生成成功，视频可下载
﻿FAILURE﻿
生成失败，查看 fail_reason﻿
﻿data.data.status 是内部状态，一般无需关心。
4.2.4 轮询建议
●轮询间隔：10–15 秒
●典型完成时间：文生视频 30s–3min，参考图生视频 2–5min，视频编辑 3–8min
●超时建议：建议客户端设置 ≥ 10 分钟超时
●高级用法：在 metadata.callback_url 里传入你的 webhook URL，可让服务端主动推送任务完成事件，避免轮询
五、使用约束与限制
5.1 视频时长约束
限制项
允许值
﻿duration﻿
整数秒，范围 [4, 15]，或 -1（自动）
﻿frames﻿
若同时传 frames 和 duration，frames 优先
5.2 参考音频约束
参考音频 reference_audio 的时长必须不超过视频时长（约 video_duration + 0.2s 的容差）。
●如果你的音频超长，必须先在本地或你的对象存储侧裁剪再传入
●示例：使用 ffmpeg 裁剪前 15 秒
此外：
●﻿audio_url 不能作为唯一输入，必须搭配 image_url 或 video_url﻿
●使用 reference_audio 时 metadata.generate_audio 必须为 true﻿
5.3 图片角色互斥
●﻿reference_image 不能与 first_frame / last_frame 同时出现在同一次请求中
●﻿first_frame 和 last_frame 可以同时使用（首尾帧模式）
5.4 素材 URL 可达性
所有 image_url / video_url / audio_url 指向的 URL 必须：
●公网 HTTPS 可访问，不能是内网地址或需要认证才能读取的私有链接
●对带宽有保障，超时下载会导致任务失败
●Content-Type 正确（例如音频是 audio/mpeg、图片是 image/jpeg 等）
推荐托管位置：国内 CDN 或对象存储（阿里云 OSS / 火山 TOS / 腾讯云 COS），避免跨境延迟。
5.5 内容安全
所有输入的文本和素材都会经过内容审核。如果命中敏感策略，任务会以 FAILURE 状态结束，fail_reason 会说明原因。常见触发项：
●涉政、涉暴、色情、低俗内容
●明显的名人肖像
●未经授权的品牌标识
如果你确认内容合规但仍被拦截，建议改写提示词、调整素材构图后重试。
六、通用错误码参考
6.1 HTTP 状态码
状态码
含义
处理建议
﻿200﻿
请求成功
检查业务字段
﻿400﻿
请求参数错误
检查 content / metadata / 互斥规则
﻿401﻿
鉴权失败
检查 Authorization header 是否带 Token
﻿403﻿
无权限访问该资源
确认 Token 是否有对应模型权限，或素材归属
﻿404﻿
任务或素材不存在
检查 ID 是否正确
﻿429﻿
请求过快，触发限流
指数退避后重试
﻿500﻿
服务端错误
稍后重试；持续出现请联系客服
6.2 常见错误与解决方法（补充）
各接口的成功/错误响应示例已放在对应章节，本节仅做排障补充。
错误信息关键字
原因
解决方法
﻿duration ... not valid﻿
﻿duration 不在合法范围
改为 [4, 15] 内的整数
﻿audio duration ... must be less than or equal to ...﻿
音频时长超过视频时长
裁剪音频到不超过视频时长
﻿reference_image ... cannot be used with first_frame﻿
角色互斥
去掉 reference_image 或改用 first_frame﻿
﻿audio_url ... at least one image or video﻿
仅音频输入
添加至少一个 image_url / video_url﻿
﻿invalid character '\n' in string literal﻿
请求 JSON 字符串里有未转义换行
在客户端用标准 JSON 库序列化，不要手动拼字符串
﻿fail_to_fetch_task﻿
素材 URL 不可达
检查素材 URL 的公网可访问性
﻿content safety / sensitive information﻿
内容审核失败
改写 prompt 或更换素材
七、最佳实践
7.1 Prompt 工程建议
●开头用镜头语言：电影级镜头切换、广角建立镜头、特写、环绕拉远 等术语能显著提升画面质感
●明确时间段：多镜头叙事建议标注时间段（例如 "0-3s: xxx, 3-6s: yyy"），模型会按节拍切换
●风格词叠加：电影胶片质感, 高对比度, 黄金时刻光线, 浅景深, 自然光 能稳定引导视觉风格
●避免否定句：说"夜晚场景"而不是"不要白天"
7.2 素材准备建议
●图片：建议 1024×1024 以上，主体清晰、构图简洁
●视频：短片段（≤ 10 秒）效果更稳定
●音频：采样率 44.1 kHz，MP3 或 WAV，时长 ≤ 目标视频时长
7.3 节约成本与时间
●预览用 draft: true：草稿模式生成速度快、费用低，适合迭代调试提示词
●并发控制：单账号建议并发 ≤ 5 个任务，避免触发限流
●回调优于轮询：生产环境建议使用 callback_url，减少无效查询请求
7.4 故障排查流程
1.查 HTTP 状态码和 error.message——95% 的问题能直接定位
2.轮询任务状态——FAILURE 时 fail_reason 字段有具体原因
3.验证素材 URL——用 curl -I <url> 确认 HTTPS 可达、Content-Type 正确
4.核对计费配置——预扣费异常一般是账号余额或模型权限问题
5.联系 gpulink 技术支持——上述步骤都无法定位时
八、FAQ
Q1: 单次请求最长能生成多长的视频？
A: Seedance 2.0 最长 15 秒。需要更长的视频可以使用"视频续写"模式（4.1.7.6）分段拼接。
Q2: 生成的视频 URL 有有效期吗？
A: 视频 URL 是临时签名链接，有效期以返回链接中的签名信息为准。建议任务完成后立即下载到你自己的存储。
Q3: 同一个 task_id 的视频能反复下载吗？
A: 在任务结果可查询期间可以反复下载；若链接失效或任务结果已清理，请重新提交生成。
Q4: 我能取消一个进行中的任务吗？
A: 当前版本不支持手动取消。任务会在 execution_expires_after 超时后自动终止。
Q5: 素材审批失败（Failed）常见原因是什么？
A: 三类原因最常见：
●内容审核不通过（色情、暴力、敏感人物）
●URL 不可达或超时
●文件格式不支持（非标准图片/视频编码）
Q6: 支持哪些 API 客户端？
A: 任何能发 HTTPS 请求的客户端都支持。官方示例使用 curl，也可以使用你现有的 HTTP 客户端或服务端 SDK 封装调用。
Q7: 视频生成的计费方式？
A: 按 token 或按时长计费，由你所在的定价套餐决定。具体费率以控制台的"定价"页面为准。
文档版本：v1.0  
最后更新：2026-04-15  
反馈渠道：gpulink MaaS 客户支持