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

# FLUX 3 视频生成

>  - 异步处理模式，返回任务 ID 用于后续查询
- 统一入口：文生视频 / 图生视频 / 视频续写 / 草稿两段式
- 输出 H.264 + AAC，自带同步音频，时长 5~20 秒
- 分辨率 hd / fhd，支持 7 种宽高比 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://gccai.heqingsong.uk/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "flux-3-video",
      "prompt": "一只橘猫跳上洒满阳光的木桌，尾巴扫过一只玻璃杯，杯子晃了晃没有倒。电影感，浅景深。",
      "duration": 5,
      "resolution": "hd",
      "aspect_ratio": "16:9"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://gccai.heqingsong.uk/v1/videos/generations"

  payload = {
      "model": "flux-3-video",
      "prompt": "一只橘猫跳上洒满阳光的木桌，尾巴扫过一只玻璃杯，杯子晃了晃没有倒。电影感，浅景深。",
      "duration": 5,
      "resolution": "hd",
      "aspect_ratio": "16:9",
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://gccai.heqingsong.uk/v1/videos/generations";

  const payload = {
    model: "flux-3-video",
    prompt: "一只橘猫跳上洒满阳光的木桌，尾巴扫过一只玻璃杯，杯子晃了晃没有倒。电影感，浅景深。",
    duration: 5,
    resolution: "hd",
    aspect_ratio: "16:9",
  };

  const headers = {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      url := "https://gccai.heqingsong.uk/v1/videos/generations"

      payload := map[string]interface{}{
          "model":        "flux-3-video",
          "prompt":       "一只橘猫跳上洒满阳光的木桌，尾巴扫过一只玻璃杯",
          "duration":     5,
          "resolution":   "hd",
          "aspect_ratio": "16:9",
      }

      jsonData, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer <token>")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "请求参数无效",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "身份验证失败，请检查您的API密钥",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "账户余额不足，请充值后再试",
      "type": "payment_required"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": 422,
      "message": "参数互斥或取值非法",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "请求过于频繁，请稍后再试",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## 认证

<ParamField header="Authorization" type="string" required>
  所有接口均需要使用 Bearer Token 进行认证

  访问 [API Key 管理页面](https://gccai.heqingsong.uk/keys) 获取 API Key：

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 生成模式

`flux-3-video` 为**统一入口**：按传参自动判定模式，也可 `mode` 显式指定。

| 模式            | 触发条件                                | 说明                 |
| ------------- | ----------------------------------- | ------------------ |
| **文生视频（t2v）** | 只传 `prompt`                         | 纯文本驱动              |
| **图生视频（i2v）** | 传 `image_urls`                      | 关键帧控制，见下方          |
| **视频续写（v2v）** | 传 `video_url` / `video_urls`        | 单价更高；同时有图和视频时按续写处理 |
| **草稿 → 正片**   | `draft:true` 或 `draft_from_task_id` | 先低价预览，再全价出片        |

`mode` 可选值：`t2v` / `i2v` / `v2v` / `draft_enhance`，或官方拼写 `text-to-video` / `image-continuation` / `video-continuation`。**显式 `mode` 优先级最高**。

### 图生视频关键帧语义

`image_urls` 中图片的**顺序即语义**，不要排序或去重：

| 张数      | 含义                                         |
| ------- | ------------------------------------------ |
| 1 张     | **起始帧**                                    |
| 2 张     | 第一张起始、第二张**结束帧**                           |
| 3\~10 张 | 首张起始、末张结束，中间关键帧**均匀分布**（建议显式指定 `duration`） |

## 请求参数

<ParamField body="model" type="string" required>
  固定值：`flux-3-video`
</ParamField>

<ParamField body="prompt" type="string" required>
  提示词。**草稿转正片（`draft_from_task_id`）时不能传**，传了会被拒绝。
</ParamField>

<ParamField body="duration" type="integer" default="5">
  时长（秒），**5\~20 的整数**，默认 `5`

  <Warning>
    **不支持** `duration: "auto"`（按秒计费需确定秒数）。不传、传 `"auto"` 或其它非整数 → 均按 **5 秒**，不报错也不自适应。
  </Warning>

  <Note>
    **视频续写**时，实际产出时长可能短于请求秒数（例如请求 5 秒产出 4 秒）。提交时按请求秒数预扣，出片后按实际计费秒数退还差额；最终以查询接口 `cost` 为准。文生 / 图生无此现象。
  </Note>
</ParamField>

<ParamField body="resolution" type="string" default="hd">
  分辨率

  * `hd`（默认；也接受 `720p`）
  * `fhd`（也接受 `1080p`）

  实测：`hd` 约 16:9 时 1280×704；`fhd` 约 1920×1088。

  <Warning>
    草稿模式（`draft:true`）**只能**使用 `hd`。
  </Warning>
</ParamField>

<ParamField body="aspect_ratio" type="string" default="auto">
  宽高比

  可选：`21:9`、`2:1`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`，或 `auto`（默认，按提示词与素材自动选择）
</ParamField>

<ParamField body="image_urls" type="string[]">
  图生视频关键帧，**1\~10** 张，公网 http(s) URL 或 base64
</ParamField>

<ParamField body="video_url" type="string">
  视频续写的输入视频（mp4，公网 URL 或 base64）
</ParamField>

<ParamField body="video_urls" type="string[]">
  同 `video_url`，取数组**第一个**（兼容写法）
</ParamField>

<ParamField body="audio" type="boolean" default="true">
  是否生成同步音频，默认 `true`。设为 `false` 出无声视频（**不降价**）
</ParamField>

<ParamField body="draft" type="boolean" default="false">
  草稿模式：约 **1/3 价**出低质预览，且只能配 `resolution: hd`
</ParamField>

<ParamField body="draft_from_task_id" type="string">
  草稿转正片：指向**自己的**一条已成功的草稿任务 ID

  * 仅可改 `resolution`；提示词、时长、图片、视频一律不能改
  * 按正片全价计费，草稿费用不抵扣
  * 与 `draft:true` **互斥**
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  内容审核宽松度 **0\~4**，默认 `2`，越大越宽松

  <Note>
    勿与 FLUX.2 图片（0~~5）或 Kontext（0~~6）混淆。
  </Note>
</ParamField>

<ParamField body="mode" type="string">
  显式指定模式（可选），见「生成模式」
</ParamField>

## 草稿模式

视频生成较贵时，可用两段式试稿：

```
第一段  draft:true            → 约 1/3 价出低质预览
第二段  draft_from_task_id    → 满意后再按全价出正片（画面与草稿一致）
```

### 出草稿

```json theme={null}
{
  "model": "flux-3-video",
  "prompt": "一只橘猫跳上洒满阳光的木桌",
  "duration": 5,
  "draft": true
}
```

### 草稿转正片

```json theme={null}
{
  "model": "flux-3-video",
  "draft_from_task_id": "task_01K_DRAFT...",
  "resolution": "fhd"
}
```

草稿转正片会使用草稿保存的原始参数（模式 / 提示词 / 种子 / 素材）进行全质量渲染。视频续写草稿转正片按续写正片单价计费。

## 请求示例

### 文生视频（竖屏）

```json theme={null}
{
  "model": "flux-3-video",
  "prompt": "雨夜的东京街头，霓虹倒映在积水里。一个人撑伞走过。",
  "duration": 8,
  "resolution": "fhd",
  "aspect_ratio": "9:16"
}
```

### 图生视频（首尾帧）

```json theme={null}
{
  "model": "flux-3-video",
  "prompt": "镜头缓缓推近，花朵从含苞到盛开",
  "image_urls": [
    "https://example.com/bud.jpg",
    "https://example.com/bloom.jpg"
  ],
  "duration": 5
}
```

### 视频续写

```json theme={null}
{
  "model": "flux-3-video",
  "prompt": "镜头继续跟随，主角转身走向远处的灯塔",
  "video_url": "https://example.com/clip.mp4",
  "duration": 5
}
```

### 无声视频

```json theme={null}
{
  "model": "flux-3-video",
  "prompt": "...",
  "audio": false
}
```

## 参数约束

| 限制                 | 值                               |
| ------------------ | ------------------------------- |
| 时长                 | 5\~20 秒整数（不支持 `auto`；`21` 会被拒绝） |
| 关键帧                | 1\~10 张                         |
| 分辨率                | 仅 `hd` / `fhd`；草稿仅 `hd`         |
| 比例                 | 仅 7 种或 `auto`                   |
| `safety_tolerance` | 0\~4                            |

### 常见提交错误（通常不扣费）

| 场景                                            | 说明                |
| --------------------------------------------- | ----------------- |
| 缺少 `prompt`                                   | 非转正片场景必填          |
| 非法 `resolution` / `aspect_ratio` / `duration` | 取值不在支持范围          |
| 关键帧 > 10                                      | 超出上限              |
| 显式 `i2v` 无图 / `v2v` 无视频                       | 模式与素材不匹配          |
| `draft:true` + `fhd`                          | 草稿只能 hd           |
| `draft_from_task_id` 无效 / 非草稿 / 未成功           | 转正片前置条件不满足        |
| 转正片时改 prompt / duration 等                     | 仅允许改 `resolution` |
| `draft` 与 `draft_from_task_id` 同时传            | 互斥                |

内容审核拒绝会进入 `failed` 终态并**全额退款**。

## 能力覆盖

| 能力                 | 状态                               |
| ------------------ | -------------------------------- |
| t2v / i2v / v2v    | ✅ 自动判定或 `mode` 指定                |
| 草稿 / 草稿转正片         | ✅ `draft` / `draft_from_task_id` |
| 同步音频               | ✅ 默认开，`audio:false` 关（不降价）       |
| 时间点关键帧 `[秒数, 图片]`  | ❌ 目前仅均匀分布关键帧数组                   |
| `duration: "auto"` | ❌ 不支持                            |

## Response

<ResponseField name="code" type="integer">
  响应状态码，成功时为 200
</ResponseField>

<ResponseField name="data" type="array">
  返回数据数组

  <Expandable title="数组元素">
    <ResponseField name="status" type="string">
      任务状态，初始为 `submitted`
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务 ID，用于查询
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  **查询任务结果**

  视频为异步任务。使用 [获取任务状态](/cn/api-reference/tasks/status) 轮询。

  建议每 **5\~10 秒**一次，客户端超时 **15 分钟**（20 秒 fhd 更慢）。实测 `t2v` + `hd` + 5 秒约 60 秒出片。

  成功后取 `result.videos[0].url`；产物已转存平台 CDN，长期可用。`cost` 为最终扣费金额。失败全额退款。
</Note>