FLUX-3-VIDEO 视频生成 API 文档

概述

FLUX-3-VIDEO 视频生成接口，支持文生视频、图生视频、视频续写三种输入方式，并提供草稿（draft）快速预览模式。

Base URL: https://api.apiverse.ai

本文档为海外版本。

认证方式

所有接口均需要在请求头中携带 API Key 进行认证：

Authorization: Bearer {YOUR_API_KEY}

快速开始

cURL 示例

创建 FLUX-3-VIDEO 任务（文生视频）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/flux-3-video" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic drone shot flying over a misty mountain range at sunrise",
    "aspectRatio": "16:9",
    "resolution": "hd",
    "duration": 5
  }'

查询任务状态

curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_abc123" \
  -H "Authorization: Bearer your_api_key_here"

查询账户余额

curl -X GET "https://api.apiverse.ai/api/v2/open/balance" \
  -H "Authorization: Bearer your_api_key_here"

接口列表

1. 创建 FLUX-3-VIDEO 任务

POST /api/v2/open/aigc/flux-3-video

创建一个 FLUX-3-VIDEO 视频生成任务。支持三种输入方式，由请求参数自动判定：

文生视频：仅提供 prompt
图生视频：提供 imageUrls（关键帧图片），可选配合 prompt
视频续写：提供 videoUrl（源视频），基于其继续生成

Content-Type: application/json

请求参数

参数	类型	必填	说明
prompt	string	否	视频描述提示词，≤5000 字符（文生视频时必填）
imageUrls	string[]	否	关键帧图片 URL 列表，最多 10 张（图生视频时提供）
videoUrl	string	否	源视频 URL（视频续写时提供）
aspectRatio	string	否	宽高比：`auto`(默认) / `21:9` / `2:1` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`
resolution	string	否	分辨率：`hd`(默认) / `fhd`。草稿模式下固定为 `hd`
duration	integer	否	视频时长（秒），范围 5~20，默认 5
audio	boolean	否	是否生成音频，默认 `true`
draft	boolean	否	草稿模式，默认 `false`。开启后生成更快、消耗更低，用于快速预览效果
draftFromTaskId	string	否	草稿转正片：填入一个已完成的草稿任务 ID，基于其增强生成正片
safetyTolerance	integer	否	安全等级，范围 0~4
taskNickname	string	否	任务昵称，便于业务侧标识
callbackUrl	string	否	任务完成后的回调通知 URL

说明：
- prompt、imageUrls、videoUrl、draftFromTaskId 至少提供其一
- 图生视频最多支持 10 张关键帧图片，超出部分将被忽略
- 草稿模式（draft: true）生成速度更快、消耗更低，适合先预览再决定是否出正片；草稿模式下分辨率强制为 hd
- 草稿转正片流程：先用 draft: true 生成草稿任务，拿到 taskId 后再发起一个带 draftFromTaskId 的任务生成正片
- 计费按视频时长（秒）计算，不同模式与分辨率档位单价不同
- 创建任务时会预扣费，余额不足将返回错误

请求示例

文生视频

{
  "prompt": "A cinematic drone shot flying over a misty mountain range at sunrise",
  "aspectRatio": "16:9",
  "resolution": "hd",
  "duration": 5
}

图生视频

{
  "prompt": "The character slowly turns and smiles",
  "imageUrls": [
    "https://example.com/keyframe1.jpg",
    "https://example.com/keyframe2.jpg"
  ],
  "aspectRatio": "9:16",
  "resolution": "fhd",
  "duration": 8
}

视频续写

{
  "prompt": "Continue the camera motion smoothly into the valley",
  "videoUrl": "https://example.com/source.mp4",
  "resolution": "hd",
  "duration": 5
}

草稿模式

{
  "prompt": "A neon city street in the rain, cyberpunk style",
  "draft": true,
  "aspectRatio": "16:9",
  "duration": 5
}

草稿转正片

{
  "draftFromTaskId": "task_20260810103000_abc12345",
  "resolution": "fhd"
}

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID，用于查询任务状态
data.status	string	任务状态，创建时固定为 `processing`
data.createdAt	string	创建时间

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260810103000_abc12345",
    "status": "processing",
    "createdAt": "2026-08-10 10:30:00"
  }
}

余额不足

{
  "code": 40001,
  "msg": "余额不足，当前余额: 0.0100 USD，需要: 0.8500 USD",
  "data": null
}

2. 查询任务状态

GET /api/v2/open/aigc/{taskId}

查询单个任务的执行状态。

路径参数

参数	类型	必填	说明
taskId	string	是	任务 ID

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID
data.status	string	任务状态：`processing` / `success` / `failed`
data.result	string[]	生成的视频 URL 列表（成功时返回）
data.errorMsg	string	错误信息（失败时返回）
data.createdAt	string	创建时间
data.updatedAt	string	更新时间

响应示例

处理中

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260810103000_abc12345",
    "status": "processing",
    "createdAt": "2026-08-10 10:30:00",
    "updatedAt": "2026-08-10 10:30:05"
  }
}

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260810103000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/08/10/output_001.mp4"
    ],
    "createdAt": "2026-08-10 10:30:00",
    "updatedAt": "2026-08-10 10:31:30"
  }
}

失败

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260810103000_abc12345",
    "status": "failed",
    "errorMsg": "生成失败：内容不符合规范",
    "createdAt": "2026-08-10 10:30:00",
    "updatedAt": "2026-08-10 10:30:45"
  }
}

3. 批量查询任务状态

POST /api/v2/open/aigc/batch

批量查询多个任务的执行状态（最多 100 个）。

请求参数

参数	类型	必填	说明
taskIds	string[]	是	任务 ID 列表，最多 100 个

请求示例

{
  "taskIds": ["task_20260810103000_abc12345", "task_20260810103200_def67890"]
}

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "tasks": [
      {
        "taskId": "task_20260810103000_abc12345",
        "status": "success",
        "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output_001.mp4"],
        "createdAt": "2026-08-10 10:30:00",
        "updatedAt": "2026-08-10 10:31:30"
      },
      {
        "taskId": "task_20260810103200_def67890",
        "status": "processing",
        "createdAt": "2026-08-10 10:32:00",
        "updatedAt": "2026-08-10 10:32:05"
      }
    ]
  }
}

4. 查询账户余额

GET /api/v2/open/balance

查询当前用户的账户余额。

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.userId	string	用户 ID
data.balance	string	可用余额（USD）
data.frozenBalance	string	冻结余额（USD）
data.currency	string	货币类型

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "userId": "user@example.com",
    "balance": "19.1500",
    "frozenBalance": "0.8500",
    "currency": "USD"
  }
}

回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 callbackUrl，系统会向该 URL 发送 POST 请求。

回调请求

Headers

Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}

Body

{
  "event": "task.completed",
  "taskId": "task_20260810103000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output_001.mp4"],
  "errorMsg": "",
  "timestamp": "2026-08-10T10:31:30+08:00",
  "signature": "a1b2c3d4e5f6..."
}

回调响应

接收方应返回 HTTP 2xx 状态码表示成功接收：

{
  "code": 0,
  "msg": "ok"
}

错误码

code	说明
0	成功
10002	参数缺失或格式错误
10005	API Key 无效或缺失
30003	任务不存在
40001	余额不足
90003	服务器内部错误

最佳实践

1. 轮询策略

建议的轮询间隔：
- 前 30 秒：每 3 秒查询一次
- 30 秒 ~ 2 分钟：每 5 秒查询一次
- 2 分钟后：每 10 秒查询一次

2. 使用回调

对于生产环境，建议使用回调通知而非轮询，可以：
- 减少 API 调用次数
- 更快获得结果通知
- 降低服务器压力

3. 草稿工作流

先用 draft: true 快速生成草稿预览，成本更低
对满意的草稿，再用 draftFromTaskId 引用其任务 ID 生成高质量正片
该流程可显著降低反复试错的成本

4. 处理时间参考

草稿模式：通常数十秒 ~ 1 分钟
正片生成：通常 1 ~ 3 分钟（根据时长与分辨率）

5. 余额管理

创建任务前建议先查询余额，避免因余额不足导致任务失败
任务成功后会从冻结余额中扣费
任务失败后冻结金额会自动退还到可用余额