EZmodel API

简体中文

English

简体中文

English

主题

Seedance 2.0 — 火山 / Ark 原生入口 ​

除了 OpenAI 兼容的 /v1/video/generations，Seedance 2.0 还提供一组 火山 Ark / BytePlus 原生风格入口，方便已经按火山文档或 BytePlus SDK 对接的客户端零改动接入。

该入口只转换请求/响应格式，上游链路、计费、分组、渠道与 /v1/video/generations 完全一致。客户体感像在直连火山 Ark，实际经 EZModel 网关结算。

等价路径 ​

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

操作方法/api/v3（与火山官方一致）/v3（常见简写）/ark/api/v3
创建视频任务POST/api/v3/contents/generations/tasks/v3/contents/generations/tasks/ark/api/v3/contents/generations/tasks
查询任务状态GET/api/v3/contents/generations/tasks/{task_id}/v3/contents/generations/tasks/{task_id}/ark/api/v3/contents/generations/tasks/{task_id}
上传素材POST/api/v3/sd/assets/v3/sd/assets/ark/api/v3/sd/assets
查询素材GET/api/v3/sd/assets/{asset_id}/v3/sd/assets/{asset_id}/ark/api/v3/sd/assets/{asset_id}

关于 /v3 简写

对接问卷或内部文档常把火山路径写成 /v3/contents/generations/tasks（省略 /api）。本平台已同时挂载 /v3 与 /api/v3，两者等价；未匹配的 /v3/* 路径会返回 API 404 JSON，而不是前端页面。

认证 ​

http
Authorization: Bearer YOUR_EZMODEL_API_KEY
Content-Type: application/json

API Key 使用 EZModel 令牌，与 /v1/video/generations 共用。

Base URL ​

text
https://www.ezmodel.cloud
# 或
https://api.ezmodel.cloud

完整示例：POST https://www.ezmodel.cloud/v3/contents/generations/tasks

创建视频 — 请求体 ​

完全遵循 Ark content-generations-tasks 规格：

字段类型必填说明
modelstring是模型名，如 dreamina-seedance-2-0-hc；若渠道配置了模型重定向，也可传 BytePlus / 火山模型 id
contentarray是内容项数组，见下
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否任务完成回调地址

content[] 支持的项类型：

type字段说明
texttext文本提示词（多项会被换行拼接）
image_urlimage_url.url + role参考图、首帧或尾帧（HTTP(S) 或 asset://{asset_id}）
video_urlvideo_url.url + role参考视频素材
audio_urlaudio_url.url + role参考音频素材，可用于人物唱歌或对口型

媒体角色：

role适用类型说明
reference_imageimage_url人物、主体、构图或风格参考
first_frameimage_url指定视频首帧
last_frameimage_url指定视频尾帧
reference_videovideo_url动作、运镜或视频风格参考
reference_audioaudio_url音频参考；配合人物图可用于唱歌、说话或对口型

自适应画幅

Seedance 支持顶层参数 "ratio": "adaptive"。带参考图时，上游会根据参考图自适应输出画幅；需要固定横竖屏时，请传明确比例（如 16:9 或 9:16）。通过 /v1/video/generations 调用时，对应字段为 metadata.ratio。

文生视频示例 ​

bash
curl https://www.ezmodel.cloud/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "A cinematic shot of a glass perfume bottle on a marble table, slow camera push in"}
    ],
    "duration": 4,
    "resolution": "720p",
    "ratio": "16:9"
  }'

响应（Ark 原生形状）：

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

图生视频 / 多参考素材示例 ​

bash
curl https://www.ezmodel.cloud/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-fast-260128",
    "content": [
      {"type": "text", "text": "Make the product rotate slowly"},
      {"type": "image_url", "image_url": {"url": "https://example.com/product.png"}},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/bgm.mp3"}, "role": "reference_audio"}
    ],
    "duration": 4,
    "resolution": "720p",
    "ratio": "adaptive"
  }'

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

真人或数字人请先通过素材接口上传人物图，然后使用 HC 模型和 asset:// 引用：

bash
curl https://www.ezmodel.cloud/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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,
    "watermark": false
  }'

首帧、尾帧与最后一帧回传 ​

bash
curl https://www.ezmodel.cloud/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-hc",
    "content": [
      {"type": "text", "text": "镜头从白天平滑过渡到夜晚"},
      {"type": "image_url", "image_url": {"url": "https://example.com/day.jpg"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/night.jpg"}, "role": "last_frame"}
    ],
    "duration": 4,
    "resolution": "720p",
    "ratio": "16:9",
    "return_last_frame": true,
    "execution_expires_after": 3600,
    "callback_url": "https://example.com/callbacks/seedance"
  }'

return_last_frame 会透传到生成服务。任务完成后，如果上游返回了最后一帧，查询响应会包含顶层 last_frame_url，可直接用于下一次生成的 first_frame。

参考视频与修改视频 ​

没有单独的视频编辑端点。把原视频作为 reference_video 创建新任务，即可按提示词修改动作、镜头、场景或风格：

json
{
  "model": "dreamina-seedance-2-0-hc",
  "content": [
    {"type": "text", "text": "保留人物和动作，把背景改成雨夜街道"},
    {"type": "video_url", "video_url": {"url": "https://example.com/source.mp4"}, "role": "reference_video"}
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}

视频也可先按 AssetType: "Video" 上传，再通过 asset:// 引用。

素材资产库（私域虚拟人像 / 真人人像） ​

虚拟人像与真人人像共用同一套素材接口。AssetType 表示媒体类型（Image / Video / Audio），不是人像类别。二者的区别在生成阶段的模型选择：真人 / 数字人请使用任一 *-hc 模型（-hc / -fast-hc / -mini-hc）。

本站使用 SD 直传通道，不需要创建素材组。data.Id 就是后续 asset:// 要使用的素材 ID；查询结果中的 GroupId 可以为 null。历史 Asset Group 通道已下线，/v1/asset-groups 与 /v1/assets 不作为本站可用接口。

上传素材 ​

bash
curl https://www.ezmodel.cloud/v3/sd/assets \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "URL": "https://example.com/avatar_front.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" }
  }
}

查询素材 ​

bash
curl https://www.ezmodel.cloud/v3/sd/assets/asset-20260726161146-sh9fq \
  -H "Authorization: Bearer $YOUR_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" }
  }
}

素材按账户隔离：不同 API Key（不同用户）之间互不可见；访问非本账户素材返回 404，错误体为：

json
{"error":{"message":"asset not found","type":"invalid_request_error"}}

用素材生成视频（hc 模型） ​

bash
curl https://www.ezmodel.cloud/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

常见错误

  • asset 不属于当前账户或不存在：引用了其他账户的素材，或素材 ID 不存在。
  • asset ... is not found：非 hc 模型无法读取 asset://，请改用任一 *-hc 模型。
  • InputImageSensitiveContentDetected.PrivacyInformation：非 HC 模型对真人图会触发隐私拦截。
  • HeightTooSmall / resource download failed：素材 URL 尺寸不符合要求，或上游无法下载，请换成公开可访问的 HTTPS 直链。

查询任务状态 ​

bash
curl https://www.ezmodel.cloud/v3/contents/generations/tasks/mvt-512d4ffd9ce54256 \
  -H "Authorization: Bearer $YOUR_API_KEY"

进行中：

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

完成（视频地址在 content.video_url）：

json
{
  "id": "mvt-512d4ffd9ce54256",
  "model": "dreamina-seedance-2-0-hc",
  "status": "succeeded",
  "content": {"video_url": "https://d1olhcno4eh2oq.cloudfront.net/media/videos/mvt-....mp4"},
  "last_frame_url": "https://.../seedance-last-frame.png",
  "usage": {"completion_tokens": 87300, "total_tokens": 87300},
  "created_at": 1782971136
}

查询字段兼容 ​

本站 Seedance 实际通过 Service Inference Video 渠道执行。该供应商会接受创建请求中的生成参数，但查询接口不一定逐项返回这些参数。为保持 Ark / V3 协议一致，网关会在创建任务时将以下已确认并实际透传的字段保存到任务私有快照：

  • model
  • duration
  • resolution
  • ratio
  • generate_audio
  • watermark
  • return_last_frame
  • execution_expires_after

查询时按“上游返回值优先、请求快照兜底”合并；布尔值 false 不会丢失。seed、framespersecond、service_tier 等没有上游值或请求值的字段不会被猜测或伪造。该快照只影响升级后新建任务，历史任务仍返回数据库中已有的上游字段。

通过 i9star 接入时，实际链路为：客户 -> i9star /v1/video/generations -> EZModel V3 -> Service Inference Video -> 原厂执行。i9star 的外层任务 ID 与 EZModel 内层任务 ID 可能不同，排查时建议同时记录。

失败：

json
{
  "id": "mvt-512d4ffd9ce54256",
  "status": "failed",
  "error": {"message": "task failed: ..."}
}

状态值映射：

内部状态Ark 返回
SUBMITTED / QUEUED / NOT_START / PENDING / CREATEDqueued
IN_PROGRESS / PROCESSING / RUNNINGprocessing
SUCCESSsucceeded
FAILUREfailed

本站只提供按任务 ID 查询，不提供 GET /v1/video/tasks 列表接口。callback_url 会透传给生成服务；请让回调服务快速、幂等地返回 2xx，收到通知后再查询一次任务详情，确认最终视频地址和 usage。

关于视频地址

任务成功后返回的 content.video_url 通常是本平台 CDN 直链（无需鉴权、可直接分享与嵌入）。响应体结构与火山一致，仅 URL 主机不同。CDN 转存失败时会回退到本站代理链接（需鉴权），两种情况都不会暴露上游原始地址。

与 OpenAI 兼容入口的关系 ​

两条入口共享同一个 token、同一个渠道、同一套计费：

  • 请求体：本入口用 content[]，/v1/video/generations 用 prompt + images + metadata；二者最终被转成同一种上游请求。
  • 响应体：本入口返回 {id, status, content:{video_url}, usage}，/v1/video/generations 返回 {task_id, status} 等形式。
  • task_id 互通：任一入口创建的任务，都可用另一入口查询（注意路径与返回结构差异）。
  • 素材接口：/v1/sd/assets 与 /v3/sd/assets（及 /api/v3/sd、/ark/api/v3/sd）完全等价。

注意事项 ​

  • 模型名建议直接用 dreamina-seedance-2-0-* 系列。若客户习惯传火山 / BytePlus 官方模型 id，请在对应渠道的「模型重定向」里映射到 dreamina-*。
  • 真人 / 数字人参考图或 asset:// 引用必须使用任一 *-hc 模型。
  • Base 支持 4k；Fast / Mini 仅支持 480p / 720p。
  • Fast 模型仅支持 480p 和 720p。
  • ratio 支持 adaptive；带参考图时可按参考图自适应画幅。OpenAI 兼容入口请使用 metadata.ratio。
  • content 中存在 HTTP(S) 或 asset:// 图片、视频、音频参考素材时进入 with_ref；纯文本任务进入 no_ref。计费规则见 Seedance 2.0 主文档。
  • 上传素材本身不计费。
  • 所有 *-ep 模型均已下线，请不要继续配置或调用。

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

Copyright © 2025-present EZmodel