跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.ominiapi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Seedance 2.0 视频生成 · API 对接文档

​
1. 接入信息

项目说明
API 地址https://www.ominiapi.com
认证方式Authorization: Bearer <API Key>
编码UTF-8，Content-Type: application/json

​
2. 可用模型

模型 ID说明
doubao-seedance-2-0-260128Seedance 2.0 标准版
doubao-seedance-2-0-fast-260128Seedance 2.0 Fast（低延迟版）

​
3. 创建视频生成任务

​
方式一：POST /v1/video/generations（JSON 格式，推荐）

创建任务： 
curl -X POST https://www.ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-fast-260128",
        "prompt": "一只猫在草地上奔跑",
        "metadata": {
            "duration": 8,
            "ratio": "16:9",
            "resolution": "720p"
        }
    }'
返回： 
{
    "id": "task_FrlY3KIt0rUFILoJ46HqfbOftAv66EXe",
    "task_id": "task_FrlY3KIt0rUFILoJ46HqfbOftAv66EXe",
    "object": "video",
    "model": "doubao-seedance-2-0-fast-260128",
    "status": "",
    "progress": 0,
    "created_at": 1777718227
}

​
4. 请求参数

​
4.0 参数传递规则（重要）

new-api 网关的视频生成接口采用两层参数结构：
层级字段说明
顶层model、prompt、seconds、image/images网关直接解析的基础字段
metadataduration、ratio、resolution、generate_audio、watermark、seed、content 等透传给火山引擎 Ark API 的所有高级参数
⚠️ 关键：ratio、resolution、generate_audio 等参数必须放在 metadata 对象中才能被正确透传到上游 API。直接放在顶层 JSON 中会被忽略！

​
4.1 顶层参数

参数类型必填默认值说明
modelstring是-模型 ID：doubao-seedance-2-0-260128 或 doubao-seedance-2-0-fast-260128
promptstring是-文本提示词（建议中文 ≤500 字、英文 ≤1000 词）
imagestring否-图生视频：单张图片 URL
imagesarray否-多张图片 URL 数组
metadataobject推荐-透传给上游 API 的参数对象（见下表）。⚠️ 时长、比例等必须放这里

​
4.2 metadata 内参数（透传给火山引擎 Ark API）

参数类型默认值说明
durationinteger5视频时长（秒），范围 4–15，可设为 -1。在 metadata 中传整数类型
ratiostring16:9宽高比（文生视频默认 16:9，图生视频默认 adaptive）
resolutionstring720p分辨率：480p、720p（Seedance 2.0 暂不支持 1080p）
generate_audiobooleantrue是否生成同步音频
watermarkbooleanfalse是否添加水印
seedinteger-1随机种子，范围 [-1, 2³²-1]
return_last_framebooleanfalse是否返回尾帧图像
camera_fixedbooleanfalse是否固定摄像头
service_tierstring-"flex" = 离线推理（约 50% 价格）
contentarray-高级内容数组（用于视频参考、音频参考等，见 4.4）

​
4.3 时长参数使用方式

经实测验证，只有 metadata.duration（整数）方式有效： 
{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "...",
    "metadata": {
        "duration": 10
    }
}
⚠️ 顶层 seconds 字段在当前 new-api 版本存在 bug（PR #4068），无法正确透传。请统一使用 metadata.duration。

​
4.4 多图模式与视频参考（metadata.content）

使用 images（顶层）传入多张图片时，系统根据图片数量自动分配角色：
图片数量角色分配说明
1 张first_frame以该图片作为视频首帧
2 张第 1 张 → first_frame，第 2 张 → last_frame指定首帧和尾帧
≥3 张全部 → reference_image作为参考图
对于更复杂的场景（视频参考、音频参考、指定角色），使用 metadata.content 数组： 
{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "结合参考视频风格生成",
    "metadata": {
        "duration": 8,
        "ratio": "16:9",
        "content": [
            {
                "type": "image_url",
                "image_url": { "url": "https://example.com/ref.jpg" },
                "role": "reference_image"
            },
            {
                "type": "video_url",
                "video_url": { "url": "https://example.com/ref.mp4" },
                "role": "reference_video"
            }
        ]
    }
}

​
5. 宽高比

值说明
16:9横屏（文生视频默认）
9:16竖屏
4:3传统横幅
3:4传统竖幅
1:1正方形
21:9超宽屏
adaptive自适应（图生视频默认）

​
6. 分辨率与输出像素

分辨率宽高比输出像素（宽×高）
480p16:9864 × 480
480p4:3736 × 544
480p1:1640 × 640
480p3:4544 × 736
480p9:16480 × 864
720p16:91248 × 704
720p4:31120 × 832
720p1:1960 × 960
720p3:4832 × 1120
720p9:16704 × 1248

​
7. 素材约束

​
7.1 图片要求（图生视频）

约束要求
格式JPEG、PNG、WebP
宽高比长边/短边在 (0.4, 2.5) 范围
宽高像素300–6000 px
单张大小≤ 30 MB

​
7.2 视频参考要求

约束要求
数量≤ 3 个
格式MP4、MOV
单片时长2–15 秒
总时长≤ 15 秒
分辨率480p–720p
帧率24–60 FPS
单片大小≤ 50 MB

​
8. 请求示例

​
8.1 文生视频

curl -X POST https://www.ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-260128",
        "prompt": "海边日落，镜头缓慢推进，光影变化细腻",
        "metadata": {
            "duration": 8,
            "ratio": "16:9",
            "resolution": "720p"
        }
    }'

​
8.2 文生视频 + 生成音频

curl -X POST https://ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-260128",
        "prompt": "雨天城市街道，行人撑伞穿行，背景有汽车经过",
        "metadata": {
            "duration": 10,
            "ratio": "16:9",
            "resolution": "720p",
            "generate_audio": true
        }
    }'

​
8.3 图生视频（图片 URL）

curl -X POST https://www.ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-260128",
        "prompt": "画面中的人物开始行走",
        "image": "https://example.com/first-frame.jpg",
        "metadata": {
            "duration": 5,
            "resolution": "720p",
            "ratio": "adaptive"
        }
    }'

​
8.4 图生视频（首尾帧，2 张图片）

curl -X POST https://www.ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-260128",
        "prompt": "平滑过渡",
        "images": [
            "https://example.com/first-frame.jpg",
            "https://example.com/last-frame.jpg"
        ],
        "metadata": {
            "duration": 8,
            "resolution": "720p"
        }
    }'

​
8.5 图生视频（参考图模式，≥3 张图片）

curl -X POST https://www.ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-260128",
        "prompt": "结合参考图风格生成一段城市夜景视频",
        "images": [
            "https://example.com/ref1.jpg",
            "https://example.com/ref2.jpg",
            "https://example.com/ref3.jpg"
        ],
        "metadata": {
            "duration": 5,
            "resolution": "720p",
            "ratio": "16:9"
        }
    }'

​
8.6 Fast 模式快速生成

curl -X POST https://www.ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-fast-260128",
        "prompt": "一只猫在草地上奔跑",
        "metadata": {
            "duration": 5,
            "ratio": "16:9"
        }
    }'

​
8.7 离线推理（flex，约 50% 价格）

curl -X POST https://ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-260128",
        "prompt": "夕阳下的城市天际线，云层翻涌",
        "metadata": {
            "duration": 10,
            "ratio": "21:9",
            "resolution": "720p",
            "service_tier": "flex"
        }
    }'

​
8.8 全参数示例（推荐写法）

curl -X POST https://www.ominiapi.com/v1/video/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 令牌token" \
    -d '{
        "model": "doubao-seedance-2-0-260128",
        "prompt": "女孩抱着狐狸，温柔地看向镜头，狐狸友善地抱着，镜头缓缓拉出",
        "image": "https://example.com/first-frame.jpg",
        "metadata": {
            "duration": 8,
            "ratio": "adaptive",
            "resolution": "720p",
            "generate_audio": true,
            "watermark": false
        }
    }'

​
9. 查询任务状态

curl -X GET https://www.ominiapi.com/v1/video/generations/{task_id} \
    -H "Authorization: Bearer 令牌token"

​
9.1 任务状态值

状态说明
（空字符串）刚提交，等待处理
IN_PROGRESS生成中
SUCCESS成功
FAILURE失败
上游原始状态值：queued→running→succeeded/failed/expired

​
9.2 查询响应示例（进行中）

{
    "id": "task_FrlY3KIt0rUFILoJ46HqfbOftAv66EXe",
    "task_id": "task_FrlY3KIt0rUFILoJ46HqfbOftAv66EXe",
    "status": "IN_PROGRESS",
    "progress": "50%"
}

​
9.3 查询响应示例（成功）

{
    "id": "task_FrlY3KIt0rUFILoJ46HqfbOftAv66EXe",
    "task_id": "task_FrlY3KIt0rUFILoJ46HqfbOftAv66EXe",
    "status": "SUCCESS",
    "progress": "100%",
    "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/..."
}
成功时视频 URL 从 url 字段获取（TOS 签名 URL，有时效性）。

​
9.4 轮询示例

TASK_ID="task_FrlY3KIt0rUFILoJ46HqfbOftAv66EXe"
while true; do
    RESULT=$(curl -s "https://www.ominiapi.com/v1/video/generations/${TASK_ID}" \
        -H "Authorization: Bearer 令牌token")
    STATUS=$(echo "$RESULT" | jq -r '.status')
    PROGRESS=$(echo "$RESULT" | jq -r '.progress // empty')
    echo "状态: $STATUS | 进度: $PROGRESS"
    if [ "$STATUS" = "SUCCESS" ] || [ "$STATUS" = "FAILURE" ]; then
        echo "$RESULT" | jq -r '.url'
        break
    fi
    sleep 5
done

​
10. 支持能力总览

能力说明关键参数
文生视频纯文本生成视频prompt（必填）
图生视频-首帧以图片为首帧生成视频img_url / image_url / image（1 张）
图生视频-首尾帧指定首帧和尾帧images（2 张）
图生视频-参考图以多张图片为风格参考images（≥3 张）
视频参考以视频为风格参考（Seedance 2.0）video / videos（最多 3 个）
音频生成生成与画面同步的音频generate_audio: true
时长控制指定视频时长 4-15 秒duration: 10（整数）
画幅比例指定视频宽高比ratio: "16:9"
尾帧返回返回最后一帧（连续拼接）return_last_frame: true
离线推理低价批量生成service_tier: "flex"

​
11. 注意事项

  1. 异步任务：创建任务返回 task_id，需轮询获取结果
  2. 视频有效期：生成的视频 URL 有时效（TOS 签名 URL，默认 24 小时），请及时下载
  3. 任务超时：默认 48 小时，超时后标记为 expired
  4. 轮询间隔：建议 5 秒；Fast 模式通常 2–3 分钟完成
  5. 所有参数必须走 metadata：duration、ratio、resolution、generate_audio、watermark 等参数必须放在 metadata 对象中（经实测验证，顶层 seconds 字段在当前版本不生效）
  6. 默认行为：generate_audio 默认 true、ratio 默认 16:9、resolution 默认 720p、duration 默认 5
  7. 提示词建议：中文 ≤500 字，英文 ≤1000 词；描述具体（主体、动作、场景、光线、镜头运动）
  8. Token 消耗：5 秒 720p ≈ 108900 tokens；10 秒 720p ≈ 216900 tokens
  9. FPS：默认输出 24fps

​
12. 与火山引擎官方 Ark API 的差异

本文档描述的是 ominiapi.com（基于 new-api 部署）封装的兼容接口，与火山引擎官方 Ark API 存在以下差异：
对比项ominiapi.com（本文档）火山引擎官方 Ark API
接口路径/v1/video/generations/api/v3/contents/generations/tasks
请求格式扁平 JSON + metadata 对象所有参数（含 content 数组）均在顶层
时长字段metadata.duration（整数）顶层 duration（整数）
比例字段metadata.ratio（字符串）顶层 ratio（字符串）
图片传入顶层 image/images（URL 数组）content 数组中 {type: "image_url", image_url: {url: "..."}, role: "..."}
视频参考metadata.content 数组顶层 content 数组中 type: "video_url"
模型名格式doubao-seedance-2-0-260128doubao-seedance-2-0-260128 或 Endpoint ID

​
官方 API 对比示例

new-api 格式（本文档）： 
{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "女孩抱着狐狸，温柔地看向镜头",
    "image": "https://example.com/first-frame.png",
    "metadata": {
        "duration": 5,
        "ratio": "adaptive",
        "generate_audio": true,
        "watermark": false
    }
}
火山引擎官方 Ark API 格式： 
{
    "model": "doubao-seedance-2-0-260128",
    "content": [
        {"type": "text", "text": "女孩抱着狐狸，温柔地看向镜头"},
        {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.png"}}
    ],
    "duration": 5,
    "ratio": "adaptive",
    "generate_audio": true,
    "watermark": false
}