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

# FLUX 3 视频生成

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

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/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://api.apimart.ai/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://api.apimart.ai/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://api.apimart.ai/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))
}
```

```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"
  }
}
```

## 认证

**Authorization** `string` *required*

所有接口均需要使用 Bearer Token 进行认证

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

```
Authorization: Bearer YOUR_API_KEY
```

## 生成模式

`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`） |

## 请求参数

**model** `string` *required*

固定值：`flux-3-video`

**nsfw\_check** `boolean` (default: false)

是否在提交视频任务前执行内容审核。

* `true`：使用 `omni-moderation-latest` 审核提示词和输入图片
* `false` 或不传：不发起审核请求，不增加审核成本与延迟（默认）

**prompt** `string` *required*

提示词。**草稿转正片（`draft_from_task_id`）时不能传**，传了会被拒绝。

**duration** `integer` (default: 5)

时长（秒），**5\~20 的整数**，默认 `5`

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

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

**resolution** `string` (default: hd)

分辨率

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

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

> [!WARNING]
>
> 草稿模式（`draft:true`）**只能**使用 `hd`。

**aspect\_ratio** `string` (default: auto)

宽高比

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

**image\_urls** `string[]`

图生视频关键帧，**1\~10** 张，公网 http(s) URL 或 base64

**video\_url** `string`

视频续写的输入视频（mp4，公网 URL 或 base64）

**video\_urls** `string[]`

同 `video_url`，取数组**第一个**（兼容写法）

**audio** `boolean` (default: true)

是否生成同步音频，默认 `true`。设为 `false` 出无声视频（**不降价**）

**draft** `boolean` (default: false)

草稿模式：约 **1/3 价**出低质预览，且只能配 `resolution: hd`

**draft\_from\_task\_id** `string`

草稿转正片：指向**自己的**一条已成功的草稿任务 ID

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

**safety\_tolerance** `integer` (default: 2)

内容审核宽松度 **0\~4**，默认 `2`，越大越宽松

> [!NOTE]
>
> 勿与 FLUX.2 图片（0~~5）或 Kontext（0~~6）混淆。

**mode** `string`

显式指定模式（可选），见「生成模式」

## 草稿模式

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

```
第一段  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

**code** `integer`

响应状态码，成功时为 200

**data** `array`

返回数据数组

**数组元素**

**status** `string`

任务状态，初始为 `submitted`

**task\_id** `string`

任务 ID，用于查询

> [!NOTE]
>
> **查询任务结果**
>
> 视频为异步任务。使用 [获取任务状态](https://docs.apimart.ai/cn/api-reference/tasks/status.md) 轮询。
>
> 建议每 **5\~10 秒**一次，客户端超时 **15 分钟**（20 秒 fhd 更慢）。实测 `t2v` + `hd` + 5 秒约 60 秒出片。
>
> 成功后取 `result.videos[0].url`；产物已转存平台 CDN，长期可用。`cost` 为最终扣费金额。失败全额退款。


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