> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inb.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 Seedance 视频任务

> 提交 Seedance 2.0 文生视频或图生视频任务，支持丰富的生成参数

## 可用模型

| 模型 ID                             | 说明                            |
| --------------------------------- | ----------------------------- |
| `doubao-seedance-2-0-260128`      | Seedance 2.0 标准版，质量更高         |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 Fast 版，速度更快、成本更低 |

## 调用流程

1. `POST /v1/videos` — 提交任务，获取 `id`（即 `task_id`）
2. `GET /v1/videos/{task_id}` — 轮询，直到 `status=completed`
3. 从 `metadata.url` 读取视频 URL，或通过
   `GET /v1/videos/{task_id}/content` 直接下载视频流

## 参数优先级

推荐使用**顶层参数**（`seconds`、`resolution`、`ratio` 等），
不要与 `metadata` 中的同名字段同时传入，否则行为由服务端决定。

## 多模态素材

首尾帧、参考视频、参考音频等复杂场景，使用 `metadata.content`
精确声明每个素材的类型（`image_url` / `video_url` / `audio_url`）
和用途（`role`）。包含 `video_url` 时，费用按视频输入规则计算。

## 分辨率说明

* `480p`：成本低、速度快，适合草稿和预览
* `720p`：适合常规生产
* `1080p`：可用性取决于上游账号权限，生产环境请先实测


## OpenAPI

````yaml /openapi/videos.zh.yaml post /v1/videos
openapi: 3.1.0
info:
  title: InfinityBlue API — 视频（Videos）
  version: 1.0.0
  summary: 统一的 AI 视频生成接口
  description: |
    视频生成类接口，采用**异步任务模型**：提交任务 → 轮询状态 → 获取结果。

    InfinityBlue 提供两套视频接口：

    - **通用视频接口** (`/v1/video/generations`)：支持 Kling、Veo 等多厂商模型，
      参数风格与 OpenAI Images API 接近，适合跨模型场景。
    - **Seedance 2.0 接口** (`/v1/videos`)：专为字节豆包 Seedance 2.0 系列优化，
      提供更丰富的 Seedance 专属参数（`seconds`、`resolution`、`ratio`、
      `generate_audio`、`camera_fixed` 等），以及首尾帧、视频参考等多模态素材支持。

    ## 典型调用流程

    1. `POST /v1/video/generations` 或 `POST /v1/videos` — 提交任务，获取 `task_id`
    2. `GET /v1/video/generations/{task_id}` 或 `GET /v1/videos/{task_id}` —
       轮询状态，直到 `status` 为 `completed` 或 `failed`
    3. 从响应的 `url` / `metadata.url` 字段或 `GET /v1/videos/{task_id}/content`
       下载视频文件

    ## 认证

    所有请求需在请求头中携带 API Key：
    ```
    Authorization: Bearer YOUR_API_KEY
    ```
  contact:
    name: InfinityBlue
    url: https://getinfinityblue.com
servers:
  - url: https://api.getinfinityblue.com
    description: 生产环境
security:
  - bearerAuth: []
tags:
  - name: 视频（Videos）
    description: |
      通用视频生成接口，支持 Kling、Veo 等多厂商模型，
      采用"提交 → 轮询 → 取结果"的异步任务模型。
  - name: Seedance 2.0
    description: |
      字节豆包 Seedance 2.0 专属视频接口，参数更丰富，
      支持首尾帧、视频参考、音频参考等多模态素材。
paths:
  /v1/videos:
    post:
      tags:
        - Seedance 2.0
      summary: 创建 Seedance 视频任务
      description: |
        创建 Seedance 2.0 视频生成任务，支持文生视频和图生视频。
        成功后返回任务对象（含 `id`），使用 `GET /v1/videos/{task_id}` 轮询进度。

        推荐将常用参数（`seconds`、`resolution`、`ratio`、`generate_audio`、
        `watermark`、`camera_fixed`、`return_last_frame`）放在请求顶层传入，
        而非放入 `metadata`（`metadata` 中的同名字段仅用于兼容旧写法）。
        视频参考、首尾帧等复杂多模态素材仍建议使用 `metadata.content`。
      operationId: createSeedanceVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SeedanceVideoCreateRequest'
            examples:
              standard_text_to_video:
                summary: 普通版文生视频
                value:
                  model: doubao-seedance-2-0-260128
                  prompt: 一只白色小猫在干净的书桌上慢慢走动，柔和日光，电影感镜头，画面稳定
                  seconds: '5'
                  resolution: 720p
                  ratio: '16:9'
                  generate_audio: false
                  watermark: false
                  camera_fixed: false
              fast_text_to_video:
                summary: Fast 版文生视频
                value:
                  model: doubao-seedance-2-0-fast-260128
                  prompt: 未来城市夜晚街道，蓝色跑车穿过霓虹灯光，低角度镜头，速度感强，画面稳定
                  seconds: '4'
                  resolution: 480p
                  ratio: '16:9'
                  generate_audio: false
                  watermark: false
              image_to_video:
                summary: 图生视频
                value:
                  model: doubao-seedance-2-0-260128
                  prompt: 让图片中的小猫轻轻转头看向镜头，背景保持不变，镜头缓慢推进，动作自然
                  image: https://example.com/cat.jpg
                  seconds: '5'
                  resolution: 720p
                  ratio: adaptive
                  generate_audio: false
                  watermark: false
              video_reference:
                summary: 视频参考 / 视频编辑
                value:
                  model: doubao-seedance-2-0-260128
                  prompt: 参考视频 1 的镜头运动，把整体风格改成柔和的日系动画风，保留原有动作节奏
                  seconds: '5'
                  resolution: 720p
                  ratio: adaptive
                  generate_audio: false
                  watermark: false
                  metadata:
                    content:
                      - type: video_url
                        role: reference_video
                        video_url:
                          url: https://example.com/reference.mp4
      responses:
        '200':
          description: 成功创建 Seedance 视频任务
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeedanceVideoTask'
              example:
                id: video_abc123
                object: video
                model: doubao-seedance-2-0-fast-260128
                status: queued
                progress: 0
                created_at: 1764347090922
                seconds: '5'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API Key 无效或缺失
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求频率超限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SeedanceVideoCreateRequest:
      type: object
      description: |
        Seedance 2.0 视频生成请求。`model` 与 `prompt` 为必填字段。
        推荐将常用参数放在请求顶层，`metadata` 仅用于兼容旧写法和复杂多模态素材。
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: |
            模型 ID。普通版质量更高，Fast 版生成速度更快、成本更低。
          enum:
            - doubao-seedance-2-0-260128
            - doubao-seedance-2-0-fast-260128
          examples:
            - doubao-seedance-2-0-260128
        prompt:
          type: string
          description: |
            文本描述提示词。建议包含主体、动作、场景、镜头、光线、风格、约束条件。
            多模态参考素材可在提示词中用"视频 1"、"图片 1"、"音频 1"等方式指代。
          examples:
            - 一只白色小猫在干净的书桌上慢慢走动，柔和日光，电影感镜头，画面稳定
        seconds:
          type: string
          description: |
            推荐使用。视频时长，单位秒，建议传字符串（如 `"5"`）。
            Seedance 2.0 通常支持 4 到 15 秒。不要与 `duration` 或
            `metadata.duration` 同时传入。
          enum:
            - '4'
            - '5'
            - '6'
            - '7'
            - '8'
            - '9'
            - '10'
            - '11'
            - '12'
            - '13'
            - '14'
            - '15'
          examples:
            - '5'
        duration:
          type: number
          description: |
            兼容字段。视频时长，单位秒。新接入推荐使用顶层 `seconds`，
            不要与 `seconds` 或 `metadata.duration` 同时传入。
          minimum: 4
          maximum: 15
          examples:
            - 5
        resolution:
          type: string
          description: |
            推荐使用。输出分辨率。`480p` 成本低速度快；`720p` 适合常规生产；
            `1080p` 可用性取决于上游账号权限，生产环境请先实测。
          enum:
            - 480p
            - 720p
            - 1080p
          examples:
            - 720p
        ratio:
          type: string
          description: |
            推荐使用。输出画面比例。`adaptive` 或 `auto` 表示跟随输入素材比例；
            无输入素材时建议显式指定具体比例。
          enum:
            - adaptive
            - auto
            - '21:9'
            - '16:9'
            - '4:3'
            - '1:1'
            - '3:4'
            - '9:16'
          examples:
            - '16:9'
        size:
          type: string
          description: |
            Sora 兼容字段，格式如 `1280x720`。新接入建议优先使用
            顶层 `resolution` + `ratio`，避免尺寸与上游枚举不匹配。
          examples:
            - 1280x720
        image:
          type: string
          description: |
            单张参考图片，URL 或 Base64。适合简单图生视频/首帧参考。
            多图、首尾帧或角色参考建议使用 `metadata.content`。
          examples:
            - https://example.com/image.jpg
        ref_images:
          type: array
          description: |
            参考图片数组，URL 或 Base64。需要明确首帧、尾帧、普通参考图角色时，
            建议使用 `metadata.content`。
          items:
            type: string
          examples:
            - - https://example.com/reference-1.jpg
              - https://example.com/reference-2.jpg
        generate_audio:
          type: boolean
          description: |
            推荐使用。是否生成同步音频。开启后可能增加生成时间。
            需要对白时，建议在 prompt 中明确台词、语气和声音环境。
          default: false
          examples:
            - false
        watermark:
          type: boolean
          description: 推荐使用。是否添加水印。对外 API 服务通常建议关闭。
          default: false
          examples:
            - false
        camera_fixed:
          type: boolean
          description: |
            推荐使用。是否固定镜头。适合商品展示、稳定构图、监控视角等场景。
            开启后可减少镜头漂移。
          default: false
          examples:
            - false
        return_last_frame:
          type: boolean
          description: |
            推荐使用。是否返回视频最后一帧。适合连续生成场景，
            可将上一段最后一帧作为下一段的首帧参考。
          default: false
          examples:
            - false
        seed:
          type: integer
          format: int64
          description: |
            随机种子。相同模型、相同素材、相同参数与相同 seed 通常结果更接近，
            但不保证完全一致。
          examples:
            - 20231234
        'n':
          type: integer
          description: |
            生成视频数量。视频异步任务建议固定为 1；
            需要多条视频时，建议提交多个独立任务以便追踪和计费。
          minimum: 1
          maximum: 1
          default: 1
          examples:
            - 1
        response_format:
          type: string
          description: 响应格式，建议使用 `url`。
          enum:
            - url
          default: url
          examples:
            - url
        user:
          type: string
          description: 用户标识，用于业务侧审计和风控，不参与生成。
          examples:
            - user-1234
        metadata:
          $ref: '#/components/schemas/SeedanceMetadata'
    SeedanceVideoTask:
      type: object
      description: Seedance 视频任务对象，兼容 OpenAI / Sora 视频任务格式。
      required:
        - id
        - object
        - model
        - status
        - progress
        - created_at
        - seconds
      properties:
        id:
          type: string
          description: 视频任务 ID。
          examples:
            - video_abc123
        object:
          type: string
          description: 对象类型，固定为 `video`。
          enum:
            - video
          examples:
            - video
        model:
          type: string
          description: 执行任务所用的模型。
          enum:
            - doubao-seedance-2-0-260128
            - doubao-seedance-2-0-fast-260128
          examples:
            - doubao-seedance-2-0-fast-260128
        status:
          type: string
          description: 任务状态。
          enum:
            - queued
            - in_progress
            - completed
            - failed
          examples:
            - queued
        progress:
          type: integer
          description: 任务进度百分比（0–100）。
          minimum: 0
          maximum: 100
          examples:
            - 0
        created_at:
          type: integer
          format: int64
          description: 任务创建时间戳（毫秒）。
          examples:
            - 1764347090922
        seconds:
          type: string
          description: 视频时长，单位秒。
          examples:
            - '5'
        completed_at:
          type: integer
          format: int64
          description: 任务完成时间戳（毫秒），完成后填充。
          examples:
            - 1764347170000
        expires_at:
          type: integer
          format: int64
          description: 任务及视频文件的过期时间戳（毫秒）。
          examples:
            - 1764433570000
        size:
          type: string
          description: 视频尺寸，格式如 `1280x720`。
          examples:
            - 1280x720
        error:
          $ref: '#/components/schemas/SeedanceVideoError'
        metadata:
          type: object
          description: 额外元数据，任务完成后通常包含 `url` 字段。
          additionalProperties: true
          properties:
            url:
              type: string
              format: uri
              description: 视频文件 URL。
              examples:
                - https://example.com/generated-video.mp4
    ErrorResponse:
      type: object
      description: 标准错误响应。
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: 错误信息。
              examples:
                - 无效的时长。支持的范围为 4 到 15 秒。
            type:
              type: string
              description: 错误类型。
              examples:
                - invalid_request_error
            param:
              type:
                - string
                - 'null'
              description: 相关参数。
              examples:
                - seconds
            code:
              type:
                - string
                - 'null'
              description: 错误代码。
              examples:
                - invalid_duration
    SeedanceMetadata:
      type: object
      description: |
        Seedance 2.0 扩展参数。一般情况下不建议将常用参数放入 `metadata`，
        请优先使用请求顶层的对应字段。`metadata.content` 仍建议用于
        视频参考、音频参考、首尾帧等复杂多模态素材。
      additionalProperties: true
      properties:
        duration:
          type: integer
          description: 不建议使用。兼容旧写法的视频时长，推荐使用顶层 `seconds`。
          minimum: 4
          maximum: 15
          examples:
            - 5
        resolution:
          type: string
          description: 不建议使用。兼容旧写法的输出分辨率，推荐使用顶层 `resolution`。
          enum:
            - 480p
            - 720p
            - 1080p
          examples:
            - 720p
        ratio:
          type: string
          description: 不建议使用。兼容旧写法的输出画面比例，推荐使用顶层 `ratio`。
          enum:
            - adaptive
            - auto
            - '21:9'
            - '16:9'
            - '4:3'
            - '1:1'
            - '3:4'
            - '9:16'
          examples:
            - '16:9'
        generate_audio:
          type: boolean
          description: 不建议使用。兼容旧写法的音频生成开关，推荐使用顶层 `generate_audio`。
          default: false
        watermark:
          type: boolean
          description: 不建议使用。兼容旧写法的水印开关，推荐使用顶层 `watermark`。
          default: false
        camera_fixed:
          type: boolean
          description: 不建议使用。兼容旧写法的固定镜头开关，推荐使用顶层 `camera_fixed`。
          default: false
        return_last_frame:
          type: boolean
          description: 不建议使用。兼容旧写法的返回最后一帧开关，推荐使用顶层 `return_last_frame`。
          default: false
        seed:
          type: integer
          format: int64
          description: 不建议使用。兼容旧写法的随机种子，推荐使用顶层 `seed`。
          examples:
            - 20231234
        content:
          type: array
          description: |
            推荐用于复杂多模态素材，包含图片参考、视频参考、音频参考，
            例如首帧、尾帧、参考视频、参考音频等。
            包含 `video_url` 类型的素材时，费用可能按视频输入规则计算。
          items:
            $ref: '#/components/schemas/SeedanceContentItem'
          examples:
            - - type: image_url
                role: first_frame
                image_url:
                  url: https://example.com/first-frame.jpg
    SeedanceVideoError:
      type: object
      description: Seedance 视频任务错误信息。
      properties:
        message:
          type: string
          description: 错误信息。
          examples:
            - generation failed
        code:
          type: string
          description: 错误码。
          examples:
            - generation_failed
    SeedanceContentItem:
      type: object
      description: |
        多模态参考素材条目。根据 `type` 填写对应的
        `image_url`、`video_url` 或 `audio_url`。
      required:
        - type
      properties:
        type:
          type: string
          description: 素材类型。
          enum:
            - image_url
            - video_url
            - audio_url
          examples:
            - image_url
        role:
          type: string
          description: |
            素材用途。不同上游版本对 `role` 的兼容程度不同；
            没有特殊需求时可不传。
          enum:
            - first_frame
            - last_frame
            - reference_image
            - reference_video
            - reference_audio
          examples:
            - first_frame
        image_url:
          $ref: '#/components/schemas/SeedanceMediaURL'
        video_url:
          $ref: '#/components/schemas/SeedanceMediaURL'
        audio_url:
          $ref: '#/components/schemas/SeedanceMediaURL'
    SeedanceMediaURL:
      type: object
      description: 媒体 URL 对象。
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: |
            媒体文件 URL，必须可被上游服务器公网直接访问。
            不建议使用需要登录、Cookie、防盗链校验、Cloudflare Challenge
            或局域网地址的链接。
          examples:
            - https://example.com/input.mp4
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        使用 Bearer Token 认证，格式：`Authorization: Bearer sk-xxxxxx`。
        在 [控制台](https://api.getinfinityblue.com/console) 获取 API Key。

````