Appearance
BytePlus Dreamina Seedance 2.0
通过 Fhddos 调用 BytePlus 海外 Dreamina Seedance 2.0 原生任务接口和素材库工作流。
本页只覆盖 海外 BytePlus Dreamina Seedance 2.0。国内 Doubao Seedance 2.0 使用独立模型、独立价格和独立素材能力,不在本页混写。
Fhddos 对外提供 BytePlus 原生接口兼容。任务创建、查询和素材库请求的字段尽可能保持 BytePlus 原生形态;任务列表、取消/删除、素材库访问会限制在当前 Fhddos 租户可见范围内。
1. 前置条件
bash
export BASE_URL="https://aiapi.fhddos.com"
export TOKEN="oh-xxxxxxxxxxxxxxxx"统一请求头:
http
Authorization: Bearer <TOKEN>
Content-Type: application/json调用方只需要使用 Fhddos 发放的 API Token。BytePlus API Key、AK/SK、ProjectName 和 Endpoint 由平台统一托管。
2. 模型
| 对外模型 | BytePlus 官方模型 | 说明 |
|---|---|---|
dreamina-seedance-2-0 | dreamina-seedance-2-0-260128 | 海外标准模型,支持 480p / 720p / 1080p / 4k |
dreamina-seedance-2-0-fast | dreamina-seedance-2-0-fast-260128 | 海外快速模型,仅支持 480p / 720p,不支持 1080p / 4k |
dreamina-seedance-2-0-mini | dreamina-seedance-2-0-mini-260615 | 海外 Mini 模型,仅支持 480p / 720p,不支持 1080p / 4k |
dreamina-seedance-2-0-filter-off | BytePlus Filter-Off 模型 | 海外标准 Filter-Off 模型,价格和能力同 dreamina-seedance-2-0 |
dreamina-seedance-2-0-fast-filter-off | BytePlus Filter-Off 模型 | 海外快速 Filter-Off 模型,价格和能力同 dreamina-seedance-2-0-fast |
请求中的 model 建议使用左侧稳定模型名。为兼容 BytePlus 官方版本号,平台也接受以下官方版本名,并在任务查询、任务列表、素材库响应和计费审计中统一归一为左侧稳定模型名:
dreamina-seedance-2-0-260128->dreamina-seedance-2-0dreamina-seedance-2-0-fast-260128->dreamina-seedance-2-0-fastdreamina-seedance-2-0-mini-260615->dreamina-seedance-2-0-mini
seedance-2-0、seedance-2-0-260128、seedance-2-0-fast、seedance-2-0-fast-260128、seedance-2-0-mini、dreamina-seedance-2.0-mini 属于控制台或资源页短 ID,不作为对外 API model 参数兼容。dreamina-seedance-2-0-filter-off-260128、dreamina-seedance-2-0-260128-filter-off、dreamina-seedance-2-0-fast-filter-off-260128、dreamina-seedance-2-0-fast-260128-filter-off 不是 BytePlus 官方模型名,平台也不做兼容映射。
查询和列表响应中的 model 回显创建请求中的 Fhddos 对外模型,避免向调用方暴露服务配置、计费明细或实现细节。计费和权限以创建请求中的 Fhddos 对外模型、最终分辨率和参考输入类型为准。
海外 BytePlus Dreamina Seedance 2.0 的 4K 示例使用 dreamina-seedance-2-0 标准模型。dreamina-seedance-2-0-fast 可用于低延迟场景,dreamina-seedance-2-0-mini 可用于更低成本场景,但两者都不能请求 1080p 或 4k。doubao-seedance-2-0-fast 和 doubao-seedance-2-0-mini 是国内 Doubao 语境下的模型名,不作为海外 BytePlus 官方可用示例。
如需锁定官方具体模型版本,请联系平台配置官方版本映射,例如 dreamina-seedance-2-0 -> dreamina-seedance-2-0-260128。Filter-Off 模型需要完成精确版本映射,避免静默降级到普通模型。
2.1 4K 能力
海外标准模型支持 4K。请求体中 resolution 使用 4k;海外 fast 和 mini 模型不支持 1080p 或 4k,需要降级到 480p / 720p。
4K 输出为 10-bit / H.265。按 ratio + resolution=4k 推导的尺寸如下:
| ratio | 4K size |
|---|---|
16:9 | 3840x2160 |
9:16 | 2160x3840 |
1:1 | 2880x2880 |
4:3 | 3326x2494 |
3:4 | 2494x3326 |
21:9 | 4398x1886 |
3. 海外价格
| SKU | 价格 |
|---|---|
dreamina-seedance-2-0-480p-novideo | $7.0/M tokens |
dreamina-seedance-2-0-480p-video | $4.3/M tokens |
dreamina-seedance-2-0-720p-novideo | $7.0/M tokens |
dreamina-seedance-2-0-720p-video | $4.3/M tokens |
dreamina-seedance-2-0-1080p-novideo | $7.7/M tokens |
dreamina-seedance-2-0-1080p-video | $4.7/M tokens |
dreamina-seedance-2-0-4k-novideo | $4.0/M tokens |
dreamina-seedance-2-0-4k-video | $2.4/M tokens |
dreamina-seedance-2-0-fast-novideo | $5.6/M tokens |
dreamina-seedance-2-0-fast-video | $3.3/M tokens |
dreamina-seedance-2-0-mini-novideo | $3.5/M tokens |
dreamina-seedance-2-0-mini-video | $2.1/M tokens |
video 表示请求包含视频参考输入;novideo 表示不包含视频参考输入。平台只对成功出片任务结算,失败任务不会按成功出片计费。
dreamina-seedance-2-0-filter-off 复用 dreamina-seedance-2-0 的全部 SKU 价格;dreamina-seedance-2-0-fast-filter-off 复用 dreamina-seedance-2-0-fast 的全部 SKU 价格。日志和任务审计仍保留创建请求中的 Filter-Off 对外模型名。
4. 任务接口
| 功能 | 路径 |
|---|---|
| 创建任务 | POST /volcark/api/v3/contents/generations/tasks |
| 查询任务 | GET /volcark/api/v3/contents/generations/tasks/{task_id} |
| 查询租户任务列表 | GET /volcark/api/v3/contents/generations/tasks |
| 取消或删除任务 | DELETE /volcark/api/v3/contents/generations/tasks/{task_id} |
需要 BytePlus 原生字段和响应的客户应使用本页的 /volcark/api/v3/... 路径。
5. 创建任务
bash
curl -X POST "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0",
"content": [
{
"type": "text",
"text": "A quiet cinematic shot of a paper boat floating on calm water, soft morning light."
}
],
"duration": 4,
"ratio": "16:9",
"resolution": "4k",
"generate_audio": false,
"watermark": true,
"return_last_frame": true,
"execution_expires_after": 3600,
"priority": 0,
"safety_identifier": "user-hash-001",
"callback_url": "https://example.com/volcark/callback"
}'Filter-Off 调用只需要替换 model,其他请求字段与普通海外 Dreamina 2.0 保持一致:
json
{
"model": "dreamina-seedance-2-0-filter-off",
"content": [
{
"type": "text",
"text": "A cinematic product shot with clean studio lighting."
}
],
"duration": 4,
"ratio": "16:9",
"resolution": "720p"
}典型响应:
json
{
"id": "cgt-20260611204121-462cw"
}Fhddos native 响应默认不追加 platform_id,以保持 BytePlus 原生响应形态。
常用字段:
| 字段 | 说明 |
|---|---|
content[] | BytePlus 多模态输入数组,至少包含 prompt 文本或参考素材 |
duration | 4-15 秒,也可按 BytePlus 官方能力传 -1 交给模型服务自动选择 |
ratio | adaptive、16:9、9:16、1:1、4:3、3:4、21:9 |
resolution | 480p、720p、1080p、4k;4K 仅标准模型支持,fast 和 mini 模型不支持 1080p / 4k |
generate_audio | 是否生成音频 |
watermark | 是否保留水印 |
return_last_frame | 成功任务中返回 content.last_frame_url |
execution_expires_after | 任务执行过期时间,官方范围通常为 3600-259200 秒 |
priority | 队列优先级 0-9 |
safety_identifier | 终端用户稳定标识,建议传哈希后的用户 ID |
callback_url | BytePlus 原生任务状态回调地址,必须是非空 HTTPS 公网 URL |
CallbackURL | 兼容别名;平台会规范化为 callback_url 后再提交给模型服务 |
Mini 边界:dreamina-seedance-2-0-mini 只支持 480p / 720p,支持音频输入参考。references.audio 或原生 content[].type=audio_url 会按普通参考音频透传;service_tier=flex、draft=true 仍会在调用 BytePlus 前被拒绝。海外 mini 默认按 BytePlus AP 区域交付;EU 区域需单独探测后再开放。
视频编辑和视频延展
BytePlus 将视频生成、视频编辑和视频延展统一在同一个任务创建接口中表达,不需要切换到新的路径。调用方通过 content[] 传入待编辑或待延展的视频、参考图片或参考音频,再用文本 prompt 描述目标效果。
| 场景 | 推荐输入 |
|---|---|
| 视频编辑 | text + video_url,video_url.role=reference_video;可额外加入 image_url.role=reference_image 或 audio_url.role=reference_audio |
| 向前或向后延展视频 | text + 1 个 video_url.role=reference_video,在 prompt 中说明 forward/backward 和是否保留原片段 |
| 多段视频衔接 | text + 2-3 个 video_url.role=reference_video,用 prompt 说明中间过渡和最终顺序 |
| 严格首帧或尾帧 | 使用 image_url.role=first_frame / last_frame;普通参考图继续使用 reference_image |
Fhddos 默认要求先通过素材库上传图片、视频或音频,等素材状态变为 Active 后再以 asset:// 传入。包含 content[].type=video_url 的任务会按视频参考输入 SKU 计费;未包含 video_url 的任务不会进入 *-video SKU。dreamina-seedance-2-0-mini 支持音频参考输入,但音频参考本身不会把任务计入 *-video SKU。
视频编辑示例:
bash
curl -X POST "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0",
"content": [
{
"type": "text",
"text": "Edit Video 1: replace the red mug with a glass teapot while preserving the original camera movement. Use Image 1 as the style reference."
},
{
"type": "video_url",
"role": "reference_video",
"video_url": {
"url": "asset://asset-20260611210200-video1"
}
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-20260611210100-image1"
}
}
],
"duration": 6,
"ratio": "16:9",
"resolution": "720p",
"generate_audio": false
}'视频延展示例:
bash
curl -X POST "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0",
"content": [
{
"type": "text",
"text": "Extend Video 1 backward with the same character, lighting, and handheld camera motion, then end with Video 1."
},
{
"type": "video_url",
"role": "reference_video",
"video_url": {
"url": "asset://asset-20260611210200-video1"
}
}
],
"duration": 6,
"ratio": "16:9",
"resolution": "720p",
"generate_audio": false
}'原生回调
POST /volcark/api/v3/contents/generations/tasks 支持在顶层传入 callback_url。平台会先校验 URL,再随创建任务请求提交给模型服务。
校验规则:
- 必须是字符串,且去除首尾空白后不能为空。
- 必须使用
https。 - 域名必须解析到公网可路由地址;本地、私网、链路本地、多播、CGNAT 等地址会被拒绝。
- 校验失败时,平台会在请求提交给模型服务前返回 HTTP
400,错误码为invalid_request。
兼容字段 CallbackURL 会被规范化为 callback_url,不会继续把 CallbackURL 原字段提交给模型服务。如果两个字段同时存在,以 callback_url 为准。
这是原生任务回调透传能力,不是 Fhddos 平台 webhook broker。回调投递、重试、签名和回调体结构均以模型服务原生能力为准。
6. 查询任务
bash
curl "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks/cgt-20260611204121-462cw" \
-H "Authorization: Bearer $TOKEN"成功响应示例:
json
{
"id": "cgt-20260611204121-462cw",
"model": "dreamina-seedance-2-0",
"status": "succeeded",
"content": {
"video_url": "https://...",
"last_frame_url": "https://..."
},
"usage": {
"completion_tokens": 40594,
"total_tokens": 40594
},
"created_at": 1781181681,
"updated_at": 1781181802,
"seed": 74719,
"resolution": "4k",
"ratio": "16:9",
"duration": 4,
"framespersecond": 24,
"service_tier": "default",
"execution_expires_after": 3600,
"generate_audio": false,
"draft": false,
"safety_identifier": "user-hash-001",
"priority": 0
}常见状态:
queuedrunningsucceededfailedexpiredcancelled
结果 URL 通常约 24 小时有效,请及时转存。若请求了 return_last_frame=true,成功结果可能包含 content.last_frame_url。
7. 查询租户任务列表
bash
curl "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks?page_num=1&page_size=20&filter.status=succeeded&filter.model=dreamina-seedance-2-0" \
-H "Authorization: Bearer $TOKEN"响应形态:
json
{
"items": [
{
"id": "cgt-20260611204121-462cw",
"status": "succeeded",
"model": "dreamina-seedance-2-0",
"execution_expires_after": 3600,
"service_tier": "default",
"safety_identifier": "user-hash-001"
}
],
"total": 1
}支持的查询参数:
| 参数 | 说明 |
|---|---|
page_num | 页码,从 1 开始 |
page_size | 每页数量 |
filter.status | queued、running、succeeded、failed、expired、cancelled |
filter.model | 创建请求中的 Fhddos 对外模型 |
filter.task_ids | 逗号分隔的 BytePlus 原生任务 ID |
列表接口是 当前 Fhddos 租户作用域内 的 BytePlus 兼容列表,不返回其他租户或账号级全量任务。
8. 取消或删除任务
bash
curl -X DELETE "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks/cgt-20260611204121-462cw" \
-H "Authorization: Bearer $TOKEN"正在运行的任务可能返回 409:
json
{
"error": {
"code": "InvalidAction.RunningTaskDeletion",
"message": "Cannot delete task because it is currently running.",
"param": "",
"type": "Conflict"
}
}Fhddos 会保留本地任务审计和计费记录。对不支持运行中删除的任务,终态任务删除会在 Fhddos 租户内本地隐藏,运行中任务返回 409。删除或取消只允许操作当前租户自己的任务。
9. 素材库工作流
素材库能力随海外 Dreamina 2.0 提供,用于完成:
- 创建素材组
- 上传图片、视频或音频素材
- 保存
CreateAsset返回的Result.Id - 使用
GetAsset查询素材生命周期,只有Active可进入生成任务
所有 Asset API 挂载在:
http
POST /volcark/?Action={ActionName}&Version=2024-01-01支持的 Action:
| 功能 | Action |
|---|---|
| 创建素材组 | CreateAssetGroup |
| 创建素材 | CreateAsset |
| 查询素材组列表 | ListAssetGroups |
| 查询素材列表 | ListAssets |
| 查询单个素材组 | GetAssetGroup |
| 查询单个素材 | GetAsset |
不开放 Update*、Delete* 和 Moderation.Strategy=Skip。
CreateAssetGroup 与 CreateAsset 成功时 Result 只返回 Id。素材状态、URL、审核或预处理失败原因不在 Create 响应中展开;调用方应保存 Result.Id,再用 GetAsset 或 ListAssets 查询生命周期。
9.1 创建素材组
bash
curl -X POST "https://aiapi.fhddos.com/volcark/?Action=CreateAssetGroup&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0-fast",
"Name": "campaign-product-shots",
"GroupType": "AIGC",
"Description": "Assets for product videos"
}'典型响应:
json
{
"ResponseMetadata": {
"Action": "CreateAssetGroup",
"Region": "ap-southeast-1",
"Service": "ark",
"Version": "2024-01-01"
},
"Result": {
"Id": "group-20260611210000-abcd1"
}
}9.2 创建素材
bash
curl -X POST "https://aiapi.fhddos.com/volcark/?Action=CreateAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0-fast",
"GroupId": "group-20260611210000-abcd1",
"URL": "https://example.com/product.png",
"AssetType": "Image",
"Name": "product-front.png"
}'说明:
AssetType支持Image、Video、Audio- 推荐使用
URL字段,平台也兼容Url/url Result.Id是后续GetAsset和asset://使用的稳定素材 ID- 素材 URL 必须公网可下载,不能依赖 Cookie、登录态或一次性链接
- 只有
Status=Active的素材才能用于视频生成
典型响应:
json
{
"ResponseMetadata": {
"Action": "CreateAsset",
"Service": "ark",
"Version": "2024-01-01"
},
"Result": {
"Id": "asset-20260611210100-efgh2"
}
}9.3 查询素材
bash
curl -X POST "https://aiapi.fhddos.com/volcark/?Action=GetAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0-fast",
"Id": "asset-20260611210100-efgh2"
}'常见状态:
ProcessingActiveFailed
CreateAsset 返回 Result.Id 后即可用 GetAsset 查询生命周期。若状态仍为 Processing,请按 2、5、10、20 秒退避轮询,直到进入 Active 或 Failed。
GetAsset 是推荐的素材生命周期轮询入口。只有 Status=Active 的素材才能作为 asset:// 传入视频生成;Status=Failed 表示审核或预处理失败,需要重新创建素材。
9.4 查询素材列表
bash
curl -X POST "https://aiapi.fhddos.com/volcark/?Action=ListAssets&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0-fast",
"Filter": {
"GroupType": "AIGC",
"GroupIds": ["group-20260611210000-abcd1"]
},
"PageNumber": 1,
"PageSize": 20
}'ListAssets 和 ListAssetGroups 只返回当前 Fhddos 租户可见的素材;调用方需按官方素材库契约提供 Filter.GroupType=AIGC。
ListAssets 会在返回当前页前,对当前页中 Processing、Pending 或空状态的素材做一次尽力刷新;它不是轮询接口,也不保证每次都能立刻拿到上游最新状态。后台任务也会兜底刷新创建 1 小时内仍处于非终态的素材,超过 1 小时后后台不再继续扫描该素材;调用方仍可显式调用 GetAsset 查询单个素材的最新状态。
典型响应:
json
{
"ResponseMetadata": {
"Action": "ListAssets",
"Service": "ark",
"Version": "2024-01-01"
},
"Result": {
"Items": [
{
"Id": "asset-20260611210100-efgh2",
"GroupId": "group-20260611210000-abcd1",
"AssetType": "Image",
"Status": "Active"
}
],
"TotalCount": 1,
"PageNumber": 1,
"PageSize": 20
}
}10. 在生成任务中使用素材
素材进入 Active 后,用 asset:// 作为 BytePlus content 输入:
bash
curl -X POST "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0-fast",
"content": [
{
"type": "text",
"text": "Use Image 1 as the opening frame, then slowly move the camera forward."
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-20260611210100-efgh2"
}
}
],
"duration": 4,
"ratio": "16:9",
"resolution": "480p",
"generate_audio": false
}'平台也接受 Asset://...,并会在转发前规范化为 asset://...。
如果素材是视频,使用 type=video_url 并设置 role=reference_video;该写法适用于视频编辑、视频延展和多段视频衔接。严格首帧或尾帧控制请改用图片素材并设置 role=first_frame / last_frame。
11. 多租户边界
| 能力 | Fhddos 行为 |
|---|---|
| 任务创建 | 请求参数尽量保持 BytePlus 原生形态,服务端兼容差异由 Fhddos 处理 |
| 任务查询 | 只能查询当前租户创建的任务,响应字段按 BytePlus 兼容层归一 |
| 任务列表 | 只返回当前租户任务,不返回 BytePlus 账号级全量任务 |
| 取消/删除 | 只能操作当前租户任务,并保留平台审计记录 |
| 素材组/素材 | 只允许访问当前租户拥有的资源 |
| 素材引用 | asset:// 会绑定到当前租户的素材资源范围,避免跨范围或跨租户误用 |
12. 常见错误
| HTTP | code | 场景 |
|---|---|---|
400 | invalid_request | 请求体不是合法 JSON,或缺少必填字段 |
400 | invalid_duration | duration 超出模型允许范围 |
400 | moderation_skip_not_allowed | 素材库请求尝试使用 Moderation.Strategy=Skip |
403 | InvalidAction | 请求了未开放的 Asset Update* / Delete* |
404 | task_not_found | 任务不存在或不属于当前租户 |
404 | ResourceNotFound.Asset | 素材不存在或不属于当前租户 |
404 | ResourceNotFound.AssetGroup | 素材组不存在或不属于当前租户 |
409 | InvalidAction.RunningTaskDeletion | 正在运行的任务暂不支持删除 |
502 | service_error | 模型服务返回异常 |
503 | service_unavailable | 当前账号暂未开通海外 Dreamina 2.0 或素材库能力 |
503 | model_mapping_required | Filter-Off 模型未完成精确官方版本映射,或映射到了普通 Dreamina 模型 |
素材库控制面接口的错误响应使用火山/BytePlus 风格 ResponseMetadata.Error。素材审核或预处理失败不是 Create 错误响应,而是在 GetAsset / ListAssets 中以 Status=Failed 体现。