EZmodel API

简体中文

English

简体中文

English

主题

Seedance 对接说明（火山 Ark 兼容） ​

本文档面向按火山 Ark API 对接 Seedance 的集成方，可直接用于联调与验收。
交付模式：完全兼容火山 API——路径、请求体、响应体与火山一致，仅 base_url 与 key 为本平台分配。

1. 基本信息 ​

项值
Base URLhttps://www.ezmodel.cloud（亦可用 https://api.ezmodel.cloud）
鉴权Authorization: Bearer {平台分配的 API Key}
Content-Typeapplication/json
视频任务路径POST/GET /v3/contents/generations/tasks（亦兼容 /api/v3/...、/ark/api/v3/...）
素材资产库路径POST/GET /v3/sd/assets（亦兼容 /api/v3/sd/...、/ark/api/v3/sd/...、/v1/sd/...）

三组前缀行为完全相同，任选其一：

用途推荐路径等价路径
创建 / 查询视频任务/v3/contents/generations/tasks/api/v3/contents/generations/tasks
/ark/api/v3/contents/generations/tasks
上传 / 查询素材/v3/sd/assets/api/v3/sd/assets
/ark/api/v3/sd/assets
/v1/sd/assets

2. 可用模型 ​

模型说明分辨率
dreamina-seedance-2-0-260128标准版480p / 720p / 1080p / 4k
dreamina-seedance-2-0-hc真人 / 数字人版（Base），支持 asset://480p / 720p / 1080p / 4k
dreamina-seedance-2-0-fast-260128Fast 版480p / 720p
dreamina-seedance-2-0-fast-hcFast 真人 / 数字人版，支持 asset://480p / 720p
dreamina-seedance-2-0-mini-260615Mini 版480p / 720p
dreamina-seedance-2-0-mini-hcMini 真人 / 数字人版，支持 asset://480p / 720p
dreamina-seedance-2-5-hcSeedance 2.5 真人 / 数字人版，支持 asset://480p / 720p

使用私域虚拟人像或真人人像素材时，必须使用任一 *-hc 模型。非 hc 版会对真人图触发隐私拦截，且无法读取 asset://。

3. 私域素材资产库接口 ​

虚拟人像与真人人像共用同一套素材接口。
AssetType 表示媒体类型（Image / Video / Audio），不是人像类别；人像类别差异体现在生成阶段的模型选择（见上节 hc 模型）。

3.1 上传素材 ​

http
POST /v3/sd/assets
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "URL": "https://example.com/avatar.jpg",
  "Name": "avatar_front",
  "AssetType": "Image"
}
字段类型必填说明
URLstring是公网可访问的 HTTPS 直链（无需 Cookie、无防盗链）；图片高度须在 300–6000px
Namestring否素材名称
AssetTypestring是Image / Video / Audio

成功响应：

json
{
  "success": true,
  "data": {
    "Id": "asset-20260726161146-sh9fq",
    "base_resp": { "status_code": 0, "status_msg": "success" }
  }
}

data.Id 即素材 ID，后续通过 asset://{Id} 引用。上传本身不计费。

本站为 SD 直传素材通道，不需要先创建 Asset Group；查询响应中的 GroupId 可能为 null。历史 /v1/asset-groups + /v1/assets 流程已下线。素材接口和视频接口使用同一个 Bearer API Key。

3.2 查询素材 ​

http
GET /v3/sd/assets/{asset_id}
Authorization: Bearer {API_KEY}

成功响应：

json
{
  "success": true,
  "data": {
    "Id": "asset-20260726161146-sh9fq",
    "Status": "Active",
    "AssetType": "Image",
    "Name": "avatar_front",
    "URL": "<素材地址>",
    "GroupId": null,
    "CreateTime": "2026-07-26T08:11:46Z",
    "UpdateTime": "2026-07-26T08:11:47Z",
    "base_resp": { "status_code": 0, "status_msg": "success" }
  }
}

3.3 账户隔离 ​

  • 素材按账户隔离，不同 API Key（不同用户）之间互不可见。
  • 访问非本账户素材返回 HTTP 404：
json
{"error":{"message":"asset not found","type":"invalid_request_error"}}
  • 在视频生成中引用他人素材会在到达上游前被拒绝，错误信息包含「不属于当前账户或不存在」，不计费。

4. 创建视频任务 ​

http
POST /v3/contents/generations/tasks
Authorization: Bearer {API_KEY}
Content-Type: application/json

4.1 文生视频 ​

json
{
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "A cinematic shot of a glass perfume bottle on a marble table"}
  ],
  "duration": 4,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": false,
  "watermark": false
}

4.2 使用素材（真人 / 数字人） ​

json
{
  "model": "dreamina-seedance-2-0-hc",
  "content": [
    {"type": "text", "text": "这位穿黑色西装的男士自信地看向镜头并微微点头微笑"},
    {"type": "image_url", "image_url": {"url": "asset://asset-20260726161146-sh9fq"}}
  ],
  "duration": 5,
  "resolution": "480p",
  "ratio": "9:16"
}

4.3 真人 / 数字人 + 参考音频 ​

json
{
  "model": "dreamina-seedance-2-0-hc",
  "content": [
    {"type": "text", "text": "人物保持身份一致，自然演唱参考音频"},
    {"type": "image_url", "image_url": {"url": "asset://asset-20260726161146-sh9fq"}, "role": "reference_image"},
    {"type": "audio_url", "audio_url": {"url": "https://example.com/vocal.mp3"}, "role": "reference_audio"}
  ],
  "duration": 5,
  "resolution": "480p",
  "ratio": "9:16",
  "generate_audio": true
}

4.4 首帧 / 尾帧与参考视频 ​

  • image_url + role=first_frame：首帧。
  • image_url + role=last_frame：尾帧。
  • video_url + role=reference_video：基于现有视频修改动作、镜头、场景或风格。
  • return_last_frame=true：请求生成服务产出最后一帧；上游返回后，本站查询响应会给出顶层 last_frame_url。

提交成功响应：

json
{
  "id": "mvt-512d4ffd9ce54256",
  "status": "queued"
}
字段类型必填说明
modelstring是模型名
contentarray是内容项：text / image_url / video_url / audio_url
durationinteger否时长（秒）
resolutionstring否480p / 720p / 1080p / 4k（Fast/Mini 仅 480p/720p）
ratiostring否支持 adaptive、16:9、9:16、1:1 等；带参考图时，adaptive 会按参考图自适应画幅
generate_audioboolean否是否生成音频
watermarkboolean否是否加水印
return_last_frameboolean否请求返回最后一帧
execution_expires_afterinteger否任务执行超时时间（秒）
callback_urlstring否任务完成回调地址，原样透传

5. 查询任务状态 ​

http
GET /v3/contents/generations/tasks/{task_id}
Authorization: Bearer {API_KEY}

进行中：

json
{"id": "mvt-512d4ffd9ce54256", "status": "processing"}

成功完成：

json
{
  "id": "mvt-512d4ffd9ce54256",
  "model": "dreamina-seedance-2-0-hc",
  "status": "succeeded",
  "content": {
    "video_url": "https://dxxxxxxxxxxxx.cloudfront.net/media/videos/mvt-....mp4"
  },
  "usage": {"completion_tokens": 87300, "total_tokens": 87300},
  "created_at": 1782971136
}
内部状态返回 status
排队中queued
处理中processing
成功succeeded
失败failed

关于视频地址 ​

任务成功后返回的 content.video_url 为本平台 CDN 直链：

  • 无需鉴权，可直接分享、嵌入与下载
  • 响应体结构与火山一致，仅 URL 主机不同（本平台 CDN，而非火山 TOS）
  • 若 CDN 转存暂时失败，会回退到本站代理链接（需鉴权）；两种情况都不会暴露上游原始地址

6. 联调检查清单 ​

#检查项期望结果
1POST /v3/sd/assets 上传一张公开图片HTTP 200，返回 data.Id
2GET /v3/sd/assets/{id} 用同一 Key 查询HTTP 200，Status=Active
3用另一账户 Key 查询同一 {id}HTTP 404，asset not found
4POST /v3/contents/generations/tasks，hc 模型 + asset://{id}HTTP 200，返回 id 与 status=queued
5hc + reference_image + reference_audio任务创建成功，可用于人物唱歌/对口型
6first_frame + last_frame两个角色字段均被接受并透传
7reference_video创建新任务，以原视频为修改参考
8带 callback_url 创建任务参数被接受；收到通知后按任务 ID 再查最终结果
5轮询 GET /v3/contents/generations/tasks/{id} 至完成status=succeeded，content.video_url 可直接访问
6浏览器或 curl 无鉴权打开 video_url返回 video/mp4

7. 常见错误 ​

现象原因处理
上传返回 URL is required请求体缺少 URL补全字段
上传返回 HeightTooSmall图片高度小于 300px换符合尺寸的图
上传返回 resource download failed上游无法下载该 URL换公开 HTTPS 直链 / 预签名地址
查询返回 404 asset not found素材不属于当前账户或不存在确认 Key 与素材 ID
生成返回「不属于当前账户或不存在」asset:// 引用了他人素材使用本账户上传的素材
生成返回 asset ... is not found非 hc 模型读 asset://改用任一 *-hc 模型
生成返回隐私拦截非 HC 模型 + 真人图改用 HC 模型

8. 问卷填写参考 ​

对接问卷中相关字段可按如下填写：

Seedance 交付模式

完全兼容火山 API，路径用 /v3/contents/generations/tasks，请求体和响应体与火山完全一致，只有 baseurl 和 key 是平台自己的。

私域虚拟人像素材资产库相关接口 / 私域真人人像素材资产库相关接口（两栏相同）

text
创建素材：POST https://www.ezmodel.cloud/v3/sd/assets
查询素材：GET  https://www.ezmodel.cloud/v3/sd/assets/{asset_id}
鉴权：Authorization: Bearer {平台分配的 key}

请求体：{"URL":"<公网图片地址>","Name":"<素材名>","AssetType":"Image"}
        AssetType 支持 Image / Video / Audio
响应体：{"success":true,"data":{"Id":"asset-xxxxxxxx","base_resp":{"status_code":0}}}

生成视频：POST https://www.ezmodel.cloud/v3/contents/generations/tasks
         通过 content[].image_url.url = "asset://{asset_id}" 引用
         真人 / 数字人请使用模型 dreamina-seedance-2-0-hc

说明：虚拟人像与真人人像共用同一套素材接口；素材按账户隔离；
      任务完成后的视频地址为本平台 CDN 直链（无需鉴权），响应结构与火山一致。

9. 相关文档 ​

企业合作联系：service@ezmodel.cloud

Copyright © 2025-present EZmodel