> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建 Flux 3 视频
> 通过文本、参考图像或首尾帧创建 Flux 3 视频，并使用 720p 或 1080p 尺寸预设。
通过文本、参考图像或首尾帧创建 Flux 3 视频。保存返回的 `id`，以轮询任务并下载完成的视频。
`POST /v1/videos` 使用 `multipart/form-data`。将控制参数作为表单字段发送。对于图像输入，请使用参考图像 URL 或起始帧和结束帧。
将 `input_reference` 与 `first_frame` 和 `last_frame` 分开。
## 选择输入模式
| 目标 | 必填字段 | 可选字段 |
| ---------- | ----------------------------------------------------- | ----------------- |
| 文生视频 | `model=flux-3`, `prompt` | `seconds`, `size` |
| HTTPS 图生视频 | `model=flux-3`, `prompt`，一个 `input_reference` URL | `seconds`, `size` |
| 有序关键帧 | `model=flux-3`, `prompt`，重复的 `input_reference` URL | `seconds`, `size` |
| 上传起始帧 | `model=flux-3`, `prompt`，一个 `first_frame` 文件 | `seconds`, `size` |
| 首尾帧视频 | `model=flux-3`, `prompt`, `first_frame`, `last_frame` | `seconds`, `size` |
## 使用参考图像
`input_reference` 字段仅接受可公开访问的 HTTPS 图像 URL。对于单张图像，发送一次该字段；对于多张图像，则按照关键帧顺序重复发送。每个字段使用一个 URL，最多共 10 个 URL。
描述生成的视频应从参考图像中保留的运动、相机行为和视觉细节。
本页顶部的请求示例展示了单图和多图输入。以下请求按提交顺序使用两张图像：
```bash theme={null}
curl \
https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
--form-string 'model=flux-3' \
--form-string 'prompt=Move smoothly through the supplied reference images in their given order. Preserve recognizable subjects and visual details as the scene changes. Keep the camera movement gentle.' \
--form-string 'seconds=5' \
--form-string 'size=1280x720' \
--form-string 'input_reference=https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png' \
--form-string 'input_reference=https://apidoc.cometapi.com/images/image/gemini/6100640_569420.png'
```
## 设置首尾帧
发送 `first_frame` 以设置起始图像。要同时设置结束图像，请包含 `last_frame`，并在 `prompt` 中描述两帧之间的运动。
如果仅设置起始帧，请省略 `last_frame`。结束帧需要同时提供 `first_frame` 和 `last_frame`。
每个字段接受一个可公开访问的 HTTPS URL 或一个 PNG 或 JPEG 文件。每个字段仅发送一次，使用 URL 或文件之一。每个文件大小不得超过 20 MiB (20 × 1024 × 1024 字节).
本页顶部的帧示例展示了 URL 输入和文件上传，并显式设置了 `seconds` 和 `size`。
## 设置时长和尺寸
将 `seconds` 显式设置为从 `5` 到 `20` 的整数。
将 `size` 设置为以下精确的 `WxH` 预设值之一：
| 分辨率档位 | 尺寸 |
| ------- | ----------- |
| `720p` | `1280x720` |
| `1080p` | `1920x1080` |
尺寸值用于选择输出分辨率档位。对于文生视频，编码尺寸可为编解码器对齐而调整。对于图生视频，参考图像也可决定最终构图和宽高比。
## 任务流程
发送 multipart 表单请求，并保存返回的 `id`。
调用 [获取 Flux 3 视频](./retrieve) 直到 `status` 为 `completed` 或 `failed`。
当任务处于 `completed` 状态时，调用 [下载 Flux 3 视频内容](./retrieve-content) 以保存 MP4 文件。
## OpenAPI
````yaml api/openapi/video/flux-3/post-create.openapi.json POST /v1/videos
openapi: 3.1.0
info:
title: Flux 3 Video Create API
version: 1.0.0
description: >-
Create a Flux 3 video from text, a reference image, or opening and closing
frames with multipart form data.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/v1/videos:
post:
summary: Create a Flux 3 video task
description: >-
Create a Flux 3 video from text, one reference image URL, or opening and
closing frames.
operationId: flux_3_create_video
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Flux3CreateRequest'
encoding:
input_reference:
contentType: text/plain
style: form
explode: true
first_frame:
contentType: image/png, image/jpeg, text/plain
last_frame:
contentType: image/png, image/jpeg, text/plain
examples:
text_to_video:
summary: Text-to-video
value:
model: flux-3
prompt: >-
A paper boat glides across a still pond while the camera
moves forward.
seconds: 5
size: 1280x720
https_image_to_video:
summary: Image-to-video with an HTTPS image
value:
model: flux-3
prompt: >-
Animate the reference scene with a slow camera move and
natural motion.
seconds: 5
size: 1280x720
input_reference: >-
https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png
first_last_frame_urls:
summary: First and last frames from URLs
value:
model: flux-3
prompt: Move smoothly from the opening to the closing scene.
seconds: 5
size: 1280x720
first_frame: https://your-image-host/first-frame.png
last_frame: https://your-image-host/last-frame.png
first_last_frame_files:
summary: First and last frames from files
value:
model: flux-3
prompt: Move smoothly from the opening to the closing scene.
seconds: 5
size: 1280x720
first_frame: '@/path/to/first-frame.png'
last_frame: '@/path/to/last-frame.png'
opening_frame_file:
summary: Opening frame from a file
value:
model: flux-3
prompt: >-
Animate the opening frame with a slow camera move and
natural motion.
seconds: 5
size: 1280x720
first_frame: '@/path/to/reference.png'
input_reference_url_pair:
summary: Ordered keyframes from image URLs
value:
model: flux-3
prompt: >-
Move smoothly through the supplied reference images in their
given order. Preserve recognizable subjects and visual
details as the scene changes. Keep the camera movement
gentle.
seconds: 5
size: 1280x720
input_reference:
- >-
https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png
- >-
https://apidoc.cometapi.com/images/image/gemini/6100640_569420.png
responses:
'200':
description: >-
Task created. Store the returned id and poll GET
/v1/videos/{task_id}.
content:
application/json:
schema:
$ref: '#/components/schemas/Flux3VideoTask'
example:
id:
task_id:
object: video
model: flux-3
status: queued
progress: 0
created_at: 1779938152
'400':
description: >-
The request is missing a required field or contains an unsupported
value.
'401':
description: The API key is missing or invalid.
security:
- bearerAuth: []
x-codeSamples:
- lang: Shell
label: Text-to-video
source: |-
curl \
https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
--form-string 'model=flux-3' \
--form-string 'prompt=A paper boat glides across a still pond while the camera moves forward.' \
--form-string 'seconds=5' \
--form-string 'size=1280x720'
- lang: Python
label: Text-to-video
source: |
import os
import requests
fields = [
("model", (None, "flux-3")),
(
"prompt",
(
None,
"A paper boat glides across a still pond while the "
"camera moves forward.",
),
),
("seconds", (None, "5")),
("size", (None, "1280x720")),
]
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={
"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]
},
files=fields,
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: Text-to-video
source: |
const form = new FormData();
form.append("model", "flux-3");
form.append(
"prompt",
"A paper boat glides across a still pond while the camera moves forward.",
);
form.append("seconds", "5");
form.append("size", "1280x720");
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
- lang: Shell
label: HTTPS image-to-video
source: |-
curl \
https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
--form-string 'model=flux-3' \
--form-string 'prompt=Animate the reference scene with a slow camera move and natural motion.' \
--form-string 'seconds=5' \
--form-string 'size=1280x720' \
--form-string 'input_reference=https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png'
- lang: Python
label: HTTPS image-to-video
source: |
import os
import requests
fields = [
("model", (None, "flux-3")),
(
"prompt",
(
None,
"Animate the reference scene with a slow camera move and "
"natural motion.",
),
),
("seconds", (None, "5")),
("size", (None, "1280x720")),
(
"input_reference",
(None, "https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png"),
),
]
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={
"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]
},
files=fields,
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: HTTPS image-to-video
source: >
const form = new FormData();
form.append("model", "flux-3");
form.append(
"prompt",
"Animate the reference scene with a slow camera move and natural motion.",
);
form.append("seconds", "5");
form.append("size", "1280x720");
form.append("input_reference",
"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png");
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
- lang: Shell
label: First and last frames from URLs
source: |-
image1=https://your-image-host/first-frame.png
image2=https://your-image-host/last-frame.png
curl \
https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
--form-string model=flux-3 \
--form-string 'prompt=Move smoothly from the opening to the closing scene.' \
--form-string seconds=5 \
--form-string size=1280x720 \
--form-string "first_frame=$image1" \
--form-string "last_frame=$image2"
- lang: Python
label: First and last frames from URLs
source: |
import os
import requests
url1 = "https://your-image-host/first-frame.png"
url2 = "https://your-image-host/last-frame.png"
prompt = "Move smoothly from the opening to the closing scene."
fields = [
("model", (None, "flux-3")),
("prompt", (None, prompt)),
("seconds", (None, "5")),
("size", (None, "1280x720")),
(
"first_frame",
(None, url1),
),
(
"last_frame",
(None, url2),
),
]
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
files=fields,
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: First and last frames from URLs
source: >
const form = new FormData();
form.append("model", "flux-3");
form.append("prompt", "Move smoothly from the opening to the closing
scene.");
form.append("seconds", "5");
form.append("size", "1280x720");
form.append(
"first_frame",
"https://your-image-host/first-frame.png",
);
form.append(
"last_frame",
"https://your-image-host/last-frame.png",
);
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: "Bearer " + process.env.COMETAPI_KEY },
body: form,
});
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
- lang: Shell
label: First and last frames from files
source: |-
curl \
https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
--form-string model=flux-3 \
--form-string 'prompt=Move smoothly from the opening to the closing scene.' \
--form-string seconds=5 \
--form-string size=1280x720 \
--form 'first_frame=@/path/to/first-frame.png;type=image/png' \
--form 'last_frame=@/path/to/last-frame.png;type=image/png'
- lang: Python
label: First and last frames from files
source: |
import os
from contextlib import ExitStack
import requests
prompt = (
"Move smoothly from the opening to the closing scene."
)
with ExitStack() as stack:
image_1 = stack.enter_context(open("/path/to/first-frame.png", "rb"))
image_2 = stack.enter_context(open("/path/to/last-frame.png", "rb"))
fields = [
("model", (None, "flux-3")),
("prompt", (None, prompt)),
("seconds", (None, "5")),
("size", (None, "1280x720")),
("first_frame", ("first-frame.png", image_1, "image/png")),
("last_frame", ("last-frame.png", image_2, "image/png")),
]
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
files=fields,
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: First and last frames from files
source: >
import { readFile } from "node:fs/promises";
const image_1 = await readFile("/path/to/first-frame.png");
const image_2 = await readFile("/path/to/last-frame.png");
const form = new FormData();
form.append("model", "flux-3");
form.append("prompt", "Move smoothly from the opening to the closing
scene.");
form.append("seconds", "5");
form.append("size", "1280x720");
form.append(
"first_frame",
new Blob([image_1], { type: "image/png" }),
"first-frame.png",
);
form.append(
"last_frame",
new Blob([image_2], { type: "image/png" }),
"last-frame.png",
);
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: "Bearer " + process.env.COMETAPI_KEY },
body: form,
});
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
- lang: Shell
label: Opening frame from a file
source: |-
curl \
https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
--form-string 'model=flux-3' \
--form-string 'prompt=Animate the opening frame with a slow camera move and natural motion.' \
--form-string 'seconds=5' \
--form-string 'size=1280x720' \
--form 'first_frame=@/path/to/reference.png;type=image/png'
- lang: Python
label: Opening frame from a file
source: |
import os
import requests
prompt = (
"Animate the opening frame with a slow camera move and "
"natural motion."
)
with open("/path/to/reference.png", "rb") as reference:
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={
"Authorization": "Bearer "
+ os.environ["COMETAPI_KEY"]
},
data={
"model": "flux-3",
"prompt": prompt,
"seconds": "5",
"size": "1280x720",
},
files={
"first_frame": (
"reference.png",
reference,
"image/png",
)
},
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: Opening frame from a file
source: |
import { readFile } from "node:fs/promises";
const reference = await readFile("/path/to/reference.png");
const form = new FormData();
form.append("model", "flux-3");
form.append(
"prompt",
"Animate the opening frame with a slow camera move and natural motion.",
);
form.append("seconds", "5");
form.append("size", "1280x720");
form.append(
"first_frame",
new Blob([reference], { type: "image/png" }),
"reference.png",
);
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
- lang: Shell
label: Ordered keyframes from image URLs
source: |-
curl \
https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
--form-string 'model=flux-3' \
--form-string 'prompt=Move smoothly through the supplied reference images in their given order. Preserve recognizable subjects and visual details as the scene changes. Keep the camera movement gentle.' \
--form-string 'seconds=5' \
--form-string 'size=1280x720' \
--form-string 'input_reference=https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png' \
--form-string 'input_reference=https://apidoc.cometapi.com/images/image/gemini/6100640_569420.png'
- lang: Python
label: Ordered keyframes from image URLs
source: |
import os
import requests
fields = [
("model", (None, "flux-3")),
("prompt", (None, "Move smoothly through the supplied reference images in their given order. Preserve recognizable subjects and visual details as the scene changes. Keep the camera movement gentle.")),
("seconds", (None, "5")),
("size", (None, "1280x720")),
("input_reference", (None, "https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png")),
("input_reference", (None, "https://apidoc.cometapi.com/images/image/gemini/6100640_569420.png")),
]
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
files=fields,
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: Ordered keyframes from image URLs
source: >
const form = new FormData();
form.append("model", "flux-3");
form.append("prompt", "Move smoothly through the supplied reference
images in their given order. Preserve recognizable subjects and
visual details as the scene changes. Keep the camera movement
gentle.");
form.append("seconds", "5");
form.append("size", "1280x720");
form.append("input_reference",
"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png");
form.append("input_reference",
"https://apidoc.cometapi.com/images/image/gemini/6100640_569420.png");
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
components:
schemas:
Flux3CreateRequest:
type: object
description: >-
Flux 3 multipart request. Choose text, input_reference URLs, or
first_frame and last_frame inputs. Keep reference-image and frame inputs
separate.
required:
- model
- prompt
not:
anyOf:
- required:
- input_reference
- first_frame
- required:
- input_reference
- last_frame
properties:
model:
type: string
const: flux-3
default: flux-3
description: Model ID for this route. Use flux-3.
prompt:
type: string
minLength: 1
description: >-
Text that describes the scene, motion, camera behavior, and visual
details that the video should preserve.
default: >-
A paper boat glides across a still pond while the camera moves
forward.
seconds:
type: integer
minimum: 5
maximum: 20
description: >-
Requested clip duration in whole seconds. Set seconds explicitly to
an integer from 5 through 20.
size:
type: string
enum:
- 1280x720
- 1920x1080
default: 1280x720
description: >-
Resolution preset in exact WxH form. Use 1280x720 for the 720p tier
or 1920x1080 for the 1080p tier. Encoded dimensions can be
codec-aligned; image-to-video framing can follow the reference
image.
input_reference:
description: >-
Reference image URLs. Send one publicly accessible HTTPS image URL
per input_reference field. For multiple images, repeat the field in
keyframe order, up to 10 URLs. This field accepts URLs only. Keep it
separate from first_frame and last_frame.
anyOf:
- type: string
format: uri
pattern: ^https://
- type: array
minItems: 1
maxItems: 10
items:
type: string
format: uri
pattern: ^https://
first_frame:
description: >-
Opening-frame image as one publicly accessible HTTPS URL or one PNG
or JPEG file. Keep each file at or below 20 MiB (20 × 1024 × 1024
bytes). Send the field once, using either a URL or a file. Pair with
last_frame to set both boundaries. Keep frame inputs separate from
input_reference.
anyOf:
- type: string
format: uri
pattern: ^https://
- type: string
format: binary
last_frame:
description: >-
Closing-frame image as one publicly accessible HTTPS URL or one PNG
or JPEG file. Keep each file at or below 20 MiB (20 × 1024 × 1024
bytes). Send the field once, using either a URL or a file. To
specify the closing image through this endpoint, send last_frame
together with first_frame. Keep frame inputs separate from
input_reference.
anyOf:
- type: string
format: uri
pattern: ^https://
- type: string
format: binary
additionalProperties: false
dependentRequired:
last_frame:
- first_frame
Flux3VideoTask:
type: object
required:
- id
- object
- model
- status
- progress
- created_at
properties:
id:
type: string
description: Task ID. Use this value as task_id in retrieve and content requests.
example:
task_id:
type: string
description: >-
Compatibility alias for id. This field can be omitted from retrieve
responses.
example:
object:
type: string
const: video
description: Object type for the asynchronous video task.
model:
type: string
const: flux-3
description: Model ID that the task uses.
status:
type: string
enum:
- queued
- in_progress
- completed
- failed
description: Task lifecycle status. Poll until the value is completed or failed.
progress:
type: integer
minimum: 0
maximum: 100
description: Task progress as a coarse percentage.
created_at:
type: integer
format: int64
description: Task creation time as a Unix timestamp in seconds.
completed_at:
type: integer
format: int64
description: >-
Task completion time as a Unix timestamp in seconds when the task
provides one.
expires_at:
type: integer
format: int64
description: >-
Result expiration time as a Unix timestamp in seconds when the task
provides one.
video_url:
type: string
format: uri
description: Video delivery URL. This field appears on completed tasks.
example: https://media.example.com/flux-3-result.mp4
error:
type: object
description: Failure details. This field appears when the task fails.
properties:
message:
type: string
description: Human-readable failure description.
code:
type: string
description: Failure code when the task provides one.
additionalProperties: true
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication. Use your CometAPI API key.
````