> ## 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.
# Crea un video Flux 3
> Crea un video Flux 3 da testo, immagini di riferimento oppure fotogrammi iniziale e finale con una preimpostazione di dimensioni 720p o 1080p.
Crea un video Flux 3 da testo, immagini di riferimento oppure fotogrammi iniziale e finale. Memorizza il valore `id` restituito per interrogare l'attività e scaricare il video completato.
`POST /v1/videos` usa `multipart/form-data`. Invia i controlli come campi del modulo. Per gli input di immagini, usa URL di immagini di riferimento oppure fotogrammi iniziale e finale.
Mantieni `input_reference` separato da `first_frame` e `last_frame`.
## Scegli una modalità di input
| Obiettivo | Campi obbligatori | Campi facoltativi |
| ----------------------------------- | -------------------------------------------------------- | ----------------- |
| Da testo a video | `model=flux-3`, `prompt` | `seconds`, `size` |
| Da immagine HTTPS a video | `model=flux-3`, `prompt`, un URL `input_reference` | `seconds`, `size` |
| Fotogrammi chiave ordinati | `model=flux-3`, `prompt`, URL `input_reference` ripetuti | `seconds`, `size` |
| Fotogramma iniziale caricato | `model=flux-3`, `prompt`, un file `first_frame` | `seconds`, `size` |
| Video con primo e ultimo fotogramma | `model=flux-3`, `prompt`, `first_frame`, `last_frame` | `seconds`, `size` |
## Usa immagini di riferimento
Il campo `input_reference` accetta solo URL di immagini HTTPS accessibili pubblicamente. Invialo una volta per una singola immagine oppure ripetilo nell'ordine dei fotogrammi chiave per più immagini. Usa un URL per campo, fino a un massimo di 10 URL in totale.
Descrivi il movimento, il comportamento della videocamera e i dettagli visivi che il video generato deve preservare dall'immagine di riferimento.
Gli esempi di richiesta nella parte superiore di questa pagina mostrano input con una singola immagine e con più immagini. La richiesta seguente usa due immagini nell'ordine in cui sono state inviate:
```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'
```
## Imposta il primo e l'ultimo fotogramma
Invia `first_frame` per impostare l'immagine iniziale. Per impostare anche l'immagine finale, includi `last_frame` e descrivi il movimento tra i due fotogrammi in `prompt`.
Per il solo fotogramma iniziale, ometti `last_frame`. Un fotogramma finale richiede sia `first_frame` sia `last_frame`.
Ogni campo accetta un URL HTTPS accessibile pubblicamente oppure un file PNG o JPEG. Invia ogni campo una volta, usando un URL o un file. Mantieni ogni file pari o inferiore a 20 MiB (20 × 1024 × 1024 byte).
Gli esempi dei fotogrammi nella parte superiore di questa pagina mostrano input URL e caricamenti di file, con `seconds` e `size` impostati esplicitamente.
## Imposta durata e dimensioni
Imposta esplicitamente `seconds` su un numero intero da `5` a `20`.
Imposta `size` su uno di questi valori preimpostati `WxH` esatti:
| Livello di risoluzione | Dimensioni |
| ---------------------- | ----------- |
| `720p` | `1280x720` |
| `1080p` | `1920x1080` |
Il valore delle dimensioni seleziona il livello di risoluzione dell'output. Per la conversione da testo a video, le dimensioni codificate possono essere adattate per l'allineamento del codec. Per la conversione da immagine a video, l'immagine di riferimento può anche determinare l'inquadratura finale e il rapporto d'aspetto.
## Flusso dell'attività
Invia la richiesta del modulo multipart e memorizza il valore `id` restituito.
Chiama [Recupera un video Flux 3](./retrieve) finché `status` non è `completed` o `failed`.
Quando l'attività è `completed`, chiama [Scarica il contenuto video Flux 3](./retrieve-content) per salvare il file 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.
````