Seedance · 火山方舟格式

接入说明

火山方舟格式的接口和火山方舟「视频生成 API」一致：路径、请求参数、返回结果、任务状态和错误码都相同。已经接入火山方舟的代码，换掉接口地址和 API Key 就能使用。

从火山方舟迁移

只需要改下面两项，模型 ID、请求参数和处理返回结果的代码都不用改：

配置	火山方舟	本平台
接口地址（base_url）	`https://ark.cn-beijing.volces.com/api/v3`	https://your-domain/ark/api/v3
API Key	火山方舟控制台创建的 API Key	在控制台 → API Keys创建
模型 ID	`doubao-seedance-2-0-260128`	相同，见模型与价格

使用官方 SDK 时，创建客户端时把 base_url 指向本平台：

创建客户端

import os

from arkruntime import Ark

client = Ark(
    base_url="https://your-domain/ark/api/v3",
    api_key=os.environ.get("ARK_API_KEY"),
)

火山方舟可以用推理接入点 ID（ep- 开头）代替模型 ID，本平台不支持推理接入点，请直接填模型 ID。

接口列表

下表的路径接在接口地址后面，和火山方舟相同。

接口	方法和路径	说明
创建视频生成任务	POST`/contents/generations/tasks`	提交任务，返回任务 ID
查询视频生成任务	GET`/contents/generations/tasks/{id}`	查询任务状态，成功后返回视频地址
查询视频生成任务列表	GET`/contents/generations/tasks`	按状态、任务 ID 或模型筛选任务
取消视频生成任务	DEL`/contents/generations/tasks/{id}`	取消排队中的任务，退回费用

SDK

可以直接使用火山方舟的官方 SDK，也可以不用 SDK，用 cURL 或任意 HTTP 库发请求。

安装

python -m pip install --upgrade arkruntime

Python：推荐 arkruntime。旧版的 volcengine-python-sdk[ark]（from volcenginesdkarkruntime import Ark）同样可以使用，传入 base_url 即可。
Go：github.com/volcengine/ark-runtime-go，用 arkruntime.WithBaseUrl 指定接口地址。
Java：com.volcengine:ark-runtime。Java SDK 会忽略 baseUrl 里的路径，直接请求域名下的 /api/v3/…，本平台在这个路径上提供同样的接口，按上面的写法填写即可。

Java 完整示例

提交任务后每 10 秒查询一次，直到任务结束：

SeedanceQuickstart.java

import com.volcengine.ark.runtime.models.content_generation.ContentGenerationTask;
import com.volcengine.ark.runtime.models.content_generation.ContentItem;
import com.volcengine.ark.runtime.models.content_generation.ContentType;
import com.volcengine.ark.runtime.models.content_generation.CreateContentGenerationTaskRequest;
import com.volcengine.ark.runtime.service.ArkService;

import java.util.Collections;

public class SeedanceQuickstart {
    public static void main(String[] args) throws InterruptedException {
        ArkService service = ArkService.builder()
                .apiKey(System.getenv("ARK_API_KEY"))
                .baseUrl("https://your-domain/ark/api/v3")
                .build();

        // 1. 提交任务，拿到任务 ID
        CreateContentGenerationTaskRequest request = CreateContentGenerationTaskRequest.builder()
                .model("doubao-seedance-2-0-260128")
                .content(Collections.singletonList(ContentItem.builder()
                        .type(ContentType.TEXT)
                        .text("清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾")
                        .build()))
                .resolution("720p")
                .ratio("16:9")
                .duration(5L)
                .build();
        String id = service.createContentGenerationTask(request).getId();
        System.out.println("任务 ID: " + id);

        // 2. 每 10 秒查询一次，直到任务结束
        while (true) {
            ContentGenerationTask task = service.getContentGenerationTask(id);
            String status = task.getStatus().getValue();
            if (status.equals("succeeded")) {
                System.out.println("视频地址: " + task.getContent().getVideoUrl());
                break;
            }
            if (!status.equals("queued") && !status.equals("running")) {
                System.out.println("任务未成功: " + status);
                if (task.getError() != null) {
                    System.out.println(task.getError().getCode() + ": " + task.getError().getMessage());
                }
                break;
            }
            Thread.sleep(10_000);
        }
        service.shutdownExecutor();
    }
}

Java SDK 0.9.0 的任务状态枚举里没有 expired，查询到超时的任务时会抛出解析异常。官方接口也是这样，可以捕获异常后按任务超时处理。

与火山方舟的差异

文生视频、图生视频（首帧、首尾帧）、多模态参考、视频编辑和延长、有声视频、回调通知都和火山方舟一致。下面这些地方有所不同：

项目	火山方舟	本平台
样片模式（draft、draft_task）	Seedance 2.5 支持	不支持，传了返回 400
`asset://`	可以引用素材库里的素材	不支持，请改用素材链接或 Base64
`return_last_frame`	可以返回尾帧图片	不支持，传 true 返回 400
`output_format`	mp4，Seedance 2.5 还支持 mov	只支持 mp4
`omni_reference_task_type`	传 auto 时由模型判断是参考生成、编辑还是延长	auto 按参考生成（reference）处理，做视频编辑或延长时请明确传 edit 或 extend
文生视频的 ratio 传 adaptive	由模型根据提示词选择画幅	按模型的默认画幅 16:9 生成
视频编辑、延长的 ratio	Seedance 2.5 只能传 adaptive	画幅跟随原视频，传什么都不生效
视频编辑的 duration	Seedance 2.5 只能传 -1	时长跟随原视频，传什么都不生效
Base64 图片	单张不超过 30 MB	单张不超过 10 MB，更大的图片请传链接
`tools`、`priority`、`watermark`	联网搜索、排队优先级、AI 生成水印	忽略，视频不带水印
`execution_expires_after`	默认 48 小时，可以设置	忽略，任务最长执行 12 小时
video_url 有效期	24 小时	视频转存到本平台，不受 24 小时限制
任务记录	保留 7 天	长期保留，可以查询全部历史任务
DELETE 已结束的任务	删除任务记录	不删除，返回 400 InvalidAction
任务 ID	`cgt-`	`video_`

视频转存失败时会退回使用上游的原始地址，这种地址可能在 24 小时后失效。建议拿到视频后及时下载到自己的存储。

和 OpenAI 格式互通

两种格式的任务是同一份：用火山方舟格式创建的任务，也可以用 GET /v1/videos/{id} 查询，或者用 GET /v1/videos/{id}/content 下载视频；用 OpenAI 格式创建的 Seedance 任务，也能用火山方舟格式查询和取消。所有任务都能在控制台 → 视频任务里看到。

错误处理

出错时返回 HTTP 4xx 或 5xx 状态码，返回结果是 {"error": {...}}，错误码与火山方舟相同，官方 SDK 会把它转成异常。错误码列表和捕获异常的写法见错误码。