> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# FLUX 3 API
> Black Forest Labs video generation API for text-to-video, image-to-video, and video extension workflows
## Overview
FLUX 3 is a Black Forest Labs video model for generating short videos from text, animating one or two image frames, or extending an existing short video. Use this page when you are ready to call the API after trying FLUX 3 in the APIXO playground.
| Capability | Value |
| ---------------------- | ----------------------------------------------------- |
| Model ID | `flux-3` |
| Modes | `text-to-video`, `image-to-video`, `video-extend` |
| Prompt length | 1-5000 characters |
| Duration | 5-20 seconds |
| Resolutions | `720p`, `1080p` |
| Aspect ratios | `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
| Image-to-video sources | 1 image URL, or 2 image URLs for start and end frames |
| Video extension source | Exactly 1 public MP4 URL, up to 50 MB and 15 seconds |
| Audio | Enabled by default with `sound: true` |
| Output | MP4 video URLs in `resultJson.resultUrls` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ------------------------------------ | ------------------------------------- |
| `POST` | `/generateTask/flux-3` | Submit a video generation task |
| `GET` | `/statusTask/flux-3?taskId={taskId}` | Poll task status and retrieve results |
All requests require your APIXO API key:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Submit requests also require:
```http theme={null}
Content-Type: application/json
```
## Copy-paste async quickstart
This minimal request submits a text-to-video task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/flux-3" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a cinematic macro shot of glass sculptures forming from liquid light",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "9:16",
"sound": true
}
}'
```
Successful response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678"
}
}
```
Save the `taskId`; you need it to poll for the final result.
## Poll for result
```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/flux-3?taskId=task_12345678" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Processing response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "processing",
"createTime": 1767965610929
}
}
```
Success response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "success",
"resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/flux-3.mp4\"]}",
"createTime": 1767965610929,
"completeTime": 1767965680929,
"costTime": 70000
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "INVALID_PARAMETER",
"failMsg": "One or more input parameters are invalid.",
"createTime": 1767965610929,
"completeTime": 1767965620132
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;
```
## Request body
### Text-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a wide cinematic desert highway at sunrise, gentle aerial camera movement",
"duration": 8,
"resolution": "1080p",
"aspect_ratio": "16:9",
"sound": true
}
}
```
### Image-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-video",
"prompt": "animate the portrait with a subtle smile and soft studio camera drift",
"image_urls": [
"https://example.com/source.png"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "9:16",
"sound": true
}
}
```
### Image-to-video with start and end frames
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-video",
"prompt": "transition smoothly from the empty room into the decorated final scene",
"image_urls": [
"https://example.com/start-frame.png",
"https://example.com/end-frame.png"
],
"duration": 10,
"resolution": "1080p",
"aspect_ratio": "16:9",
"sound": false
}
}
```
### Video extend
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "video-extend",
"prompt": "continue the camera move forward as the scene opens into a bright atrium",
"video_urls": [
"https://example.com/source.mp4"
],
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
"sound": true
}
}
```
## Parameters
Result delivery mode. Omit this field or use `async` for polling with `statusTask`, or use `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
FLUX 3 input parameters.
Generation mode. Supported values: `text-to-video`, `image-to-video`, `video-extend`.
Text prompt describing the desired video. Supports 1-5000 characters. Empty prompts are rejected.
Output duration in seconds. Supports integers or integer strings from `5` through `20`. Decimal values are not valid.
Output resolution. Supported values: `720p`, `1080p`.
Output aspect ratio. Supported values: `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.
Whether to generate synchronized audio. Supported values: `true`, `false`. Audio does not add a separate charge.
Reference image URLs. Required for `image-to-video`. Provide 1 public image URL, or 2 public image URLs where the first URL is the start frame and the second URL is the end frame.
Source video URLs. Required for `video-extend`. Provide exactly 1 public MP4 URL. The source video must be no larger than 50 MB and no longer than 15 seconds.
### Mode options
| Mode | Required media | Use case |
| ---------------- | ----------------------------------- | ------------------------------------------------------------------ |
| `text-to-video` | None | Generate a video from a prompt |
| `image-to-video` | `image_urls` with 1 or 2 URLs | Animate one image, or generate motion between start and end frames |
| `video-extend` | `video_urls` with exactly 1 MP4 URL | Continue an existing short video |
## Response format
### Submit task response
`POST /generateTask/flux-3` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique task identifier used with the status endpoint.
### Status response fields
Unique task identifier.
Current task state: `pending`, `processing`, `processing_r2`, `success`, or `failed`.
JSON string containing generated video URLs in `resultUrls`. Present when `state` is `success`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds when available.
## Webhook callback mode
Use callback mode when your backend should receive the final result automatically instead of polling.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/flux-3" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "image-to-video",
"prompt": "turn the product photo into a premium reveal shot with slow camera motion",
"image_urls": [
"https://example.com/product.png"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "9:16",
"sound": true
}
}'
```
Callback delivery uses the same final payload shape as the status response. See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
FLUX 3 is billed per output second. The selected `resolution` determines the per-second unit price, and `duration` determines the billable seconds. `text-to-video`, `image-to-video`, start/end-frame image-to-video, and `video-extend` use the same resolution-based pricing.
| Resolution | APIXO price | Example total |
| ---------- | ---------------- | ------------- |
| `720p` | `$0.17 / second` | 5s: `$0.85` |
| `1080p` | `$0.29 / second` | 10s: `$2.90` |
Formula:
```text theme={null}
total cost = duration * resolution unit price
```
Audio generation with `sound: true` does not add a separate charge. For the latest published pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Actual latency may vary by prompt complexity, selected mode, media accessibility, duration, resolution, and current queue load.
| Request shape | Typical generation time | Recommended first poll | Poll interval |
| ------------------- | ----------------------- | ------------------------ | ------------- |
| `5-8` second clip | 60s-120s | 60s after task creation | 5s-10s |
| `9-15` second clip | 120s-240s | 90s after task creation | 10s |
| `16-20` second clip | 240s+ | 120s after task creation | 10s-15s |
For production video workloads, use callback mode to avoid frequent polling while generation is still running.
For `image-to-video`, use `image_urls` with either 1 or 2 URLs. Two URLs represent the start and end frames in order.
For `video-extend`, use one public MP4 URL. Keep the source file under 50 MB and at or below 15 seconds.
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| `400` | Invalid request body, missing `mode`, missing `prompt`, invalid media input, invalid `duration`, invalid `resolution`, or invalid `aspect_ratio` | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `403` | This API key cannot access the model | Check account permissions |
| `404` | Task not found when polling | Check the `taskId` |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Internal error or unknown task failure | Retry with backoff or contact support if it persists |
| `502` | Generation service or network error | Retry with backoff |
| `503` | Service temporarily unavailable | Retry later |
| `504` | Generation timeout | Retry later or use callback mode for long-running jobs |
### Validation notes
| Parameter | Backend behavior |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input.mode` | Required. Values are trimmed and lowercased. Must be `text-to-video`, `image-to-video`, or `video-extend`. |
| `input.prompt` | Required string. Must not be empty and must not exceed 5000 characters. |
| `input.duration` | Optional. Defaults to `5`. Accepts an integer or an integer string from `5` through `20`; decimals are rejected. |
| `input.resolution` | Optional. Defaults to `720p`. `720p` and `1080p` are accepted after trimming and lowercasing. |
| `input.aspect_ratio` | Optional. Defaults to `9:16`. Must be one of `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` when provided. |
| `input.sound` | Optional. Defaults to `true`. Must be a boolean value. |
| `input.image_urls` | Required for `image-to-video`. Must contain 1 or 2 non-empty public image URLs. |
| `input.video_urls` | Required for `video-extend`. Must contain exactly 1 non-empty public MP4 URL; the source must be no larger than 50 MB and no longer than 15 seconds. |
See [Error Codes](/docs/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/docs/models)
* [Video Models](/docs/models/video)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Try FLUX 3 in the APIXO Playground](https://apixo.ai/models/flux-3)
* [Pricing](https://apixo.ai/pricing)