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

# FLUX 3 Max 关键帧生视频

> FLUX 3 Max 关键帧生视频 API 通过 frame_index 把 1–10 张图片放到 24 fps 时间轴上，生成它们之间 5–20 秒的连贯运动。

> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。

FLUX 3 Max 关键帧生视频可以把最多 10 张图片固定在 24 fps 时间轴的指定位置，并生成它们之间的运动。适合分镜动画、产品变形和延时风格的序列等需要特定画面在特定时刻出现的场景。

FLUX 3 Max 是 fal 与 Black Forest Labs 合作、在 FLUX 3 视频基座上后训练的视频模型。Vidgo 提供三个 model ID：[文生视频](https://docs.vidgo.ai/zh/api-manual/video-series/blackforestlabs-flux-3-max-text-to-video.md)、[图生视频](https://docs.vidgo.ai/zh/api-manual/video-series/blackforestlabs-flux-3-max-image-to-video.md)和[关键帧生视频](https://docs.vidgo.ai/zh/api-manual/video-series/blackforestlabs-flux-3-max-keyframes-to-video.md)。

## 模型

* **blackforestlabs/flux-3-max/keyframes-to-video** — FLUX 3 Max 关键帧生视频，用 `frame_index` 放置 1–10 张图片。

## 功能

* 关键帧控制：1–10 张图片，每张放在 24 fps 时间轴的某一帧上。
* 时长为 5 到 20 秒的整数，720p 或 1080p。
* 八种宽高比；`auto` 跟随第一张关键帧图片。
* 默认开启原生音频。

## 必填参数

* `keyframes`（object\[]）：1–10 个对象，每个对象只有两个字段：
  * `image_url`（string）：关键帧图片的公开 HTTP(S) URL（PNG、JPEG 或 WebP）。
  * `frame_index`（integer）：该图片在 24 fps 时间轴上的位置，取值 `0` 到 `duration × 24`，不能重复。
* `prompt`（string）：关键帧之间的运动与过渡、镜头运动，以及开启 `sound` 时的声音。不能为空白。

## 可选参数

* `duration`（integer）：输出时长，`5`–`20` 秒。默认 `5`。
* `resolution`（string）：`720p` 或 `1080p`。默认 `720p`。
* `aspect_ratio`（string）：`auto`、`21:9`、`2:1`、`16:9`、`4:3`、`1:1`、`3:4` 或 `9:16`。默认 `auto`。
* `sound`（boolean）：随视频生成原生音频。默认 `true`；设为 `false` 输出无声视频。

## 时长

`frame_index` 按 24 fps 计帧，因此最大可用序号取决于 `duration`：

| `duration` | 可用的 `frame_index` 范围 |
| - | - |
| 5 | 0–120 |
| 10 | 0–240 |
| 15 | 0–360 |
| 20 | 0–480 |

要把图片放在第 *t* 秒，使用 `frame_index = t × 24`（例如 2.5 秒 → 60）。

## 输出

任务完成后，[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)和回调内容的 `files` 数组中会返回一个 MP4 视频。

## 示例

* **5 秒内三个关键帧**：种子、树苗和花开分别放在第 `0`、`60`、`120` 帧（5 秒视频的开头、中间和结尾）。
* **10 秒 1080p 分镜，带回调**：四个镜头放在第 `0`、`96`、`168`、`240` 帧，`21:9`，无声，并提供 `callback_url`。

## 注意事项

* `frame_index` 超过 `duration × 24`、序号重复或关键帧对象中有多余字段都会返回 400。缩短 `duration` 时请确认所有序号仍在范围内。
* 上文未列出的字段（如 `image_urls`）会返回 400。只需首尾帧时，请用 [FLUX 3 Max 图生视频](https://docs.vidgo.ai/zh/api-manual/video-series/blackforestlabs-flux-3-max-image-to-video.md)。
* 积分在提交时预扣，取决于 `resolution` 和 `duration`。文生视频、图生视频和关键帧生视频的费率相同，`sound` 不影响价格。任务失败会全额退还。当前费率见[定价页](https://vidgo.ai/apis/api-pricing)。
* 本模型没有 4K 档位、不支持 `seed`，输出最长 20 秒。


## OpenAPI

````yaml zh/api-manual/video-series/blackforestlabs-flux-3-max-keyframes-to-video.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - FLUX 3 Max 关键帧生视频
  description: >-
    FLUX 3 Max 关键帧生视频 API 通过 frame_index 把 1–10 张图片放到 24 fps 时间轴上，生成它们之间 5–20
    秒的连贯运动。
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Video Series
      summary: FLUX 3 Max 关键帧生视频
      description: >-
        只传本模型列出的 `input` 字段。其他字段（包括 `image_urls`）都会返回 400。每个关键帧需要一个公开 HTTP(S) 的
        `image_url`，以及取值在 0 到 `duration × 24` 之间且不重复的 `frame_index`。
      operationId: submit_blackforestlabs_flux_3_max_keyframes_to_video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  description: 模型 ID，填 `blackforestlabs/flux-3-max/keyframes-to-video`。
                  example: blackforestlabs/flux-3-max/keyframes-to-video
                callback_url:
                  type: string
                  format: uri
                  nullable: true
                  description: >-
                    可选的公开 HTTP(S) 地址，任务变为 `finished` 或 `failed` 时会收到 POST
                    请求。建议使用 HTTPS。省略、传 `null` 或空字符串即不发送回调。
                  example: https://your-domain.com/callback
                input:
                  type: object
                  required:
                    - keyframes
                    - prompt
                  properties:
                    keyframes:
                      type: array
                      items:
                        type: object
                        required:
                          - image_url
                          - frame_index
                        properties:
                          image_url:
                            type: string
                            format: uri
                            description: 关键帧图片的公开 HTTP(S) URL（PNG、JPEG 或 WebP）。
                          frame_index:
                            type: integer
                            minimum: 0
                            maximum: 480
                            description: >-
                              在 24 fps 时间轴上的帧位置，取值 `0` 到 `duration × 24`（例如 5
                              秒视频为 0–120）。
                        additionalProperties: false
                        description: 一个关键帧。
                      minItems: 1
                      maxItems: 10
                      description: 1–10 个关键帧。每个对象只能包含 `image_url` 和 `frame_index`，帧序号不能重复。
                    prompt:
                      type: string
                      minLength: 1
                      example: >-
                        A seed sprouts, grows into a sapling and blossoms into a
                        cherry tree, time-lapse, fixed camera
                      description: 描述关键帧之间的运动与过渡、镜头运动，以及开启 `sound` 时的声音。不能为空白。
                    duration:
                      type: integer
                      minimum: 5
                      maximum: 20
                      default: 5
                      description: 输出时长，单位秒（整数）。
                    resolution:
                      type: string
                      enum:
                        - 720p
                        - 1080p
                      default: 720p
                      description: 输出分辨率，决定计费档位。
                    aspect_ratio:
                      type: string
                      enum:
                        - auto
                        - '21:9'
                        - '2:1'
                        - '16:9'
                        - '4:3'
                        - '1:1'
                        - '3:4'
                        - '9:16'
                      default: auto
                      description: 输出宽高比。`auto` 由模型决定：纯文本时为 16:9，有输入图片时跟随第一张图片的比例。
                    sound:
                      type: boolean
                      default: true
                      description: 在同一次生成中输出原生音频。设为 `false` 生成无声视频。不影响价格。
                  additionalProperties: false
                  description: 生成参数。
            examples:
              three_keyframes:
                summary: 5 秒内三个关键帧
                value:
                  model: blackforestlabs/flux-3-max/keyframes-to-video
                  input:
                    keyframes:
                      - image_url: https://example.com/seed.png
                        frame_index: 0
                      - image_url: https://example.com/sapling.png
                        frame_index: 60
                      - image_url: https://example.com/blossom.png
                        frame_index: 120
                    prompt: >-
                      A seed sprouts, grows into a sapling and blossoms into a
                      cherry tree, time-lapse, fixed camera
                    duration: 5
                    resolution: 720p
                    aspect_ratio: auto
                    sound: true
              storyboard:
                summary: 10 秒 1080p 分镜，带回调
                value:
                  model: blackforestlabs/flux-3-max/keyframes-to-video
                  callback_url: https://your-domain.com/callback
                  input:
                    keyframes:
                      - image_url: https://example.com/shot-1.png
                        frame_index: 0
                      - image_url: https://example.com/shot-2.png
                        frame_index: 96
                      - image_url: https://example.com/shot-3.png
                        frame_index: 168
                      - image_url: https://example.com/shot-4.png
                        frame_index: 240
                    prompt: >-
                      A courier cycles through a misty city at dawn, crosses a
                      bridge and arrives at a lit doorway, smooth tracking shots
                    duration: 10
                    resolution: 1080p
                    aspect_ratio: '21:9'
                    sound: false
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - data
                properties:
                  code:
                    type: integer
                    enum:
                      - 200
                    description: HTTP 状态码。
                  data:
                    type: object
                    required:
                      - task_id
                      - status
                      - created_time
                    properties:
                      task_id:
                        type: string
                        description: >-
                          任务
                          ID，用于[查询任务状态](/zh/api-manual/task-management/status)。
                      status:
                        type: string
                        enum:
                          - not_started
                        description: 任务的初始状态。
                      created_time:
                        type: string
                        format: date-time
                        description: 任务创建时间（ISO 8601）。
              example:
                code: 200
                data:
                  task_id: task-unified-1762160000-abc123
                  status: not_started
                  created_time: '2026-11-03T10:30:00'
        '400':
          description: 输入无效、字段不受支持、媒体无法访问或积分不足
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '401':
          description: 凭证无效
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '403':
          description: 拒绝访问
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '404':
          description: 模型未知或已停用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '408':
          description: 请求超时
          content:
            text/plain:
              schema:
                type: string
              example: Request timeout
        '422':
          description: JSON 无效或请求体不是对象
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '429':
          description: 超出速率限制或 API Key 积分限额
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '500':
          description: 内部错误
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '502':
          description: 无法创建上游生成任务
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '503':
          description: 所请求的模型暂时不可用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证


        获取 API Key：


        进入 **仪表盘 → API 密钥**（[API Key
        管理页面](https://vidgo.ai/apis/dashboard/api-key)）获取你的 API Key


        在请求头中添加：


        ```

        Authorization: Bearer VIDGO_API_KEY

        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.