Flux 3 Max API, Flux 3 Klien API, Flux Kontext, Flux Dev, Flux Pro, Flux 2 Pro, Flux Schnell API: Pricing, Documentation

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-max/v1/text-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "A red panda walks along a mossy log in a sunlit forest, pausing to sniff the air.", "duration": 5, "resolution": "720p"}'

Callback Payload (success)

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-max",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Failure callback shape

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-max",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one video. batch_size, num_images, number_of_images, n and count are rejected — send one request per video.
• Set the length with duration, in whole seconds from 5 to 20 (5 when you leave it out); seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Set the resolution with resolution: 720p or 1080p, written exactly as listed (720p when you leave it out).
• Send every field at the top level of the JSON body, with the text in prompt; parameters, content and text are rejected.
• Text-to-video takes no images: image_url, end_image_url, keyframes, image_urls, image and images are rejected (use the Image to Video or Keyframes to Video operation).
• Omit a field instead of sending null.
• Use the JSON types shown: duration and seed are whole numbers (5, not "5"), and generate_audio is true or false, not a string.
• Results are always returned as a URL in output.media_url; sync_mode is accepted only as false.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.
• Options this API does not offer are rejected: model, videos and video_url.

Length and Resolution

Set duration to the length you want in whole seconds, from 5 to 20; 5 applies when you leave it out. Set resolution to one of the values below; 720p applies when you leave it out. Billing is per second of the requested duration at the rate for the requested resolution, so a longer or higher-resolution video costs more.

Example: an 8-second vertical video at 1080p

{
  "prompt": "A paper boat drifts down a rain-soaked street at dusk, reflections on the water.",
  "aspect_ratio": "9:16",
  "duration": 8,
  "resolution": "1080p"
}

Aspect Ratio

Set aspect_ratio to auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 or 9:16; auto applies when you leave it out, and auto gives 16:9 for a text prompt. It does not change the amount billed.

Audio

Audio is generated with the video unless you set generate_audio to false. Turning audio on or off does not change the price.

Example: turn audio off and use low reasoning

{
  "prompt": "Waves roll onto a quiet beach at sunrise.",
  "generate_audio": false,
  "reasoning_level": "low",
  "duration": 5,
  "resolution": "720p"
}

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing prompt (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'prompt' is required",
  "violations": [
    "'prompt' is required"
  ]
}

A value that is not allowed (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"720p\", \"1080p\" (got \"4K\")",
  "violations": [
    "'resolution' must be one of: \"720p\", \"1080p\" (got \"4K\")"
  ]
}

A value out of range (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'duration' must be <= 20 (got 21)",
  "violations": [
    "'duration' must be <= 20 (got 21)"
  ]
}

A number sent as a string (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'duration' must be integer (got string)",
  "violations": [
    "'duration' must be integer (got string)"
  ]
}

More than one video per request (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'num_images' must be one of:  (got 2); 'num_images' is not supported: FLUX 3 Max returns one video per request. Send one request per video.",
  "violations": [
    "'num_images' must be one of:  (got 2)",
    "'num_images' is not supported: FLUX 3 Max returns one video per request. Send one request per video."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the video from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-max",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/flux-3-max/v1/text-to-video.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the video from output.media_url.

How Billing Is Measured

Billing is measured per second of the requested duration, at the rate for the requested resolution: the amount is the per-second rate for resolution (720p when you leave it out) times duration (5 seconds when you leave it out). Higher resolutions cost more per second. The prompt, seed, aspect ratio, reasoning level and audio setting do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails. The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-max/v1/image-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "The subject turns slowly toward the camera and smiles, gentle push-in.", "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg", "duration": 5, "resolution": "720p"}'

Callback Payload (success)

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-max",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Failure callback shape

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-max",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one video. batch_size, num_images, number_of_images, n and count are rejected — send one request per video.
• Set the length with duration, in whole seconds from 5 to 20 (5 when you leave it out); seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Set the resolution with resolution: 720p or 1080p, written exactly as listed (720p when you leave it out).
• Send every field at the top level of the JSON body, with the text in prompt; parameters, content and text are rejected.
• Send the first frame as image_url and, optionally, the last frame as end_image_url; keyframes, image_urls, image and images are rejected.
• Omit a field instead of sending null.
• Use the JSON types shown: duration and seed are whole numbers (5, not "5"), and generate_audio is true or false, not a string.
• Results are always returned as a URL in output.media_url; sync_mode is accepted only as false.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.
• Options this API does not offer are rejected: model, videos and video_url.

Length and Resolution

Set duration to the length you want in whole seconds, from 5 to 20; 5 applies when you leave it out. Set resolution to one of the values below; 720p applies when you leave it out. Billing is per second of the requested duration at the rate for the requested resolution, so a longer or higher-resolution video costs more.

Example: an 8-second video at 1080p

{
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
  "prompt": "Slow orbit around the subject, soft morning light.",
  "duration": 8,
  "resolution": "1080p"
}

Source Image

• Send the first frame in image_url: a publicly reachable https URL (recommended) or a data URI such as data:image/png;base64,.... A list of images is rejected.
• Optionally send the last frame in end_image_url, in the same form.
• Use PNG, JPEG or WebP files. Each image is downloaded when you submit: a URL that cannot be downloaded, or a very large file, may be refused at once with a 400, with nothing charged.
• Set the frame shape with aspect_ratio; auto follows your image. With aspect_ratio left on auto, the video keeps the aspect ratio of your image.
• Describe how the video unfolds in prompt (required).

Example: set both the first and the last frame

{
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
  "end_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
  "prompt": "The subject turns away and back again.",
  "duration": 6,
  "resolution": "720p"
}

Audio

Audio is generated with the video unless you set generate_audio to false. Turning audio on or off does not change the price. With generate_audio left on, image-to-video output includes generated sound.

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. An image that cannot be downloaded is also refused at submit with a 400, and its hold is released at once: nothing is charged. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing image_url (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'image_url' is required",
  "violations": [
    "'image_url' is required"
  ]
}

A value that is not allowed (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"720p\", \"1080p\" (got \"1440p\")",
  "violations": [
    "'resolution' must be one of: \"720p\", \"1080p\" (got \"1440p\")"
  ]
}

A value out of range (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'duration' must be >= 5 (got 4)",
  "violations": [
    "'duration' must be >= 5 (got 4)"
  ]
}

A number sent as a string (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'duration' must be integer (got string)",
  "violations": [
    "'duration' must be integer (got string)"
  ]
}

A field this API does not accept (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'video_url' must be one of:  (got \"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg\"); 'video_url' is not supported: this API takes no input video.",
  "violations": [
    "'video_url' must be one of:  (got \"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg\")",
    "'video_url' is not supported: this API takes no input video."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the video from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-max",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/flux-3-max/v1/image-to-video.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the video from output.media_url.

How Billing Is Measured

Billing is measured per second of the requested duration, at the rate for the requested resolution: the amount is the per-second rate for resolution (720p when you leave it out) times duration (5 seconds when you leave it out). Higher resolutions cost more per second. The prompt, seed, aspect ratio, reasoning level and audio setting do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails. The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-max/v1/keyframes-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "The scene moves smoothly from the first keyframe to the second, soft morning light.", "keyframes": [{"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg", "frame_index": 0}, {"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg", "frame_index": 120}], "duration": 5, "resolution": "720p"}'

Callback Payload (success)

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-max",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Failure callback shape

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-max",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one video. batch_size, num_images, number_of_images, n and count are rejected — send one request per video.
• Set the length with duration, in whole seconds from 5 to 20 (5 when you leave it out); seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Set the resolution with resolution: 720p or 1080p, written exactly as listed (720p when you leave it out).
• Send every field at the top level of the JSON body, with the text in prompt; parameters, content and text are rejected.
• Send 1 to 10 keyframes, each an object with image_url and frame_index (a whole number from 0 to duration × 24, different for every keyframe); image_url, end_image_url, image_urls, image and images are rejected.
• Omit a field instead of sending null.
• Use the JSON types shown: duration and seed are whole numbers (5, not "5"), and generate_audio is true or false, not a string.
• Results are always returned as a URL in output.media_url; sync_mode is accepted only as false.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.
• Options this API does not offer are rejected: model, videos and video_url.

Length and Resolution

Set duration to the length you want in whole seconds, from 5 to 20; 5 applies when you leave it out. Set resolution to one of the values below; 720p applies when you leave it out. Billing is per second of the requested duration at the rate for the requested resolution, so a longer or higher-resolution video costs more.

Example: three keyframes over 10 seconds at 1080p

{
  "prompt": "The camera follows the subject from one keyframe to the next.",
  "keyframes": [
    {
      "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
      "frame_index": 0
    },
    {
      "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
      "frame_index": 120
    },
    {
      "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
      "frame_index": 240
    }
  ],
  "duration": 10,
  "resolution": "1080p"
}

Keyframes

• Send 1 to 10 items in keyframes. Each item is an object with image_url and frame_index.
• frame_index is the position of the image in the video: a whole number from 0 (the first frame) to duration × 24 (the last frame), different for every keyframe. For a 5-second video, 120 is the last frame.
• Use PNG, JPEG or WebP images, as publicly reachable https URLs (recommended) or data URIs. Very many or very large inputs may be refused at once with a 400, with nothing charged; so may a URL that cannot be downloaded.
• A keyframe set the model cannot use, such as a frame_index above duration × 24 or used twice, ends the request with status: "ERROR", and its hold is released.

Example: pin the last frame of a 6-second video (6 x 24 = 144)

{
  "prompt": "The subject walks toward the camera.",
  "keyframes": [
    {
      "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
      "frame_index": 0
    },
    {
      "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
      "frame_index": 144
    }
  ],
  "duration": 6,
  "resolution": "720p"
}

Aspect Ratio

Set aspect_ratio to auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 or 9:16; auto applies when you leave it out, and auto follows the first keyframe image. It does not change the amount billed.

Audio

Audio is generated with the video unless you set generate_audio to false. Turning audio on or off does not change the price.

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. An input that cannot be downloaded is also refused at submit with a 400, and so may be very many or very large inputs; the hold is then released at once: nothing is charged. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing keyframes (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'keyframes' is required",
  "violations": [
    "'keyframes' is required"
  ]
}

More than 10 keyframes (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'keyframes' must have at most 10 items (got 11)",
  "violations": [
    "'keyframes' must have at most 10 items (got 11)"
  ]
}

A value that is not allowed (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'aspect_ratio' must be one of: \"auto\", \"21:9\", \"2:1\", \"16:9\", \"4:3\", \"1:1\", \"3:4\", \"9:16\" (got \"32:9\")",
  "violations": [
    "'aspect_ratio' must be one of: \"auto\", \"21:9\", \"2:1\", \"16:9\", \"4:3\", \"1:1\", \"3:4\", \"9:16\" (got \"32:9\")"
  ]
}

A length field other than duration (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'seconds' must be one of:  (got 8); 'seconds' is not supported. Set the length with 'duration' (whole seconds, 5-20).",
  "violations": [
    "'seconds' must be one of:  (got 8)",
    "'seconds' is not supported. Set the length with 'duration' (whole seconds, 5-20)."
  ]
}

More than one video per request (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'num_images' must be one of:  (got 2); 'num_images' is not supported: FLUX 3 Max returns one video per request. Send one request per video.",
  "violations": [
    "'num_images' must be one of:  (got 2)",
    "'num_images' is not supported: FLUX 3 Max returns one video per request. Send one request per video."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the video from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-max",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/flux-3-max/v1/keyframes-to-video.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the video from output.media_url.

How Billing Is Measured

Billing is measured per second of the requested duration, at the rate for the requested resolution: the amount is the per-second rate for resolution (720p when you leave it out) times duration (5 seconds when you leave it out). Higher resolutions cost more per second. The prompt, seed, aspect ratio, reasoning level and audio setting do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails. The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-klein/v1/text-to-image' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "A red fox standing in fresh snow at sunrise, soft golden light, pine forest in the background", "aspect_ratio": "16:9", "resolution": "1k"}'

Callback Payload (success)

{
  "request_id": "flux-3-klein_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-klein",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Failure callback shape

{
  "request_id": "flux-3-klein_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-klein",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one image. batch_size, num_images, number_of_images, n and count are rejected — send one request per image.
• This API makes still images and has no length setting. duration, seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Send every field at the top level of the JSON body; parameters, input, content and text are rejected.
• To edit or compose images, use the FLUX 3 Klein edit API: POST https://gateway.pixazo.ai/flux-3-klein-edit/v1/edit-image. image_urls, image_url and image are rejected here.
• images is not accepted by text to image. Use the FLUX 3 Klein edit API to edit or combine images.
• Leave aspect_ratio out for a square image (1:1) and resolution out for 1k.
• image_size is no longer accepted: FLUX 3 Klein now takes aspect_ratio (for example "16:9") and resolution (768sq, 1k, 1.5k, 2k or 4k) instead.
• output_format is no longer accepted: the output is always a JPEG image.
• bounding_boxes, enable_prompt_expansion and enable_safety_checker are not supported on this API.
• sync_mode is not supported on this API: requests are asynchronous; poll the status URL for the result.
• Use the JSON types shown: prompt, aspect_ratio and resolution are strings, and seed is a whole number. aspect_ratio and resolution take exactly the values listed.
• Omit a field instead of sending null.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.
• stream is not supported: the result is delivered when the job completes.
• Options this API does not offer are rejected: width, height, steps and safety_tolerance.

Output Size and Layout

• Choose the layout with aspect_ratio: wide (21:9 to 5:4), square (1:1) or tall (4:5 to 9:21). 1:1 applies when you leave it out; auto lets the model choose the shape from the prompt.
• Choose the size with resolution: 768sq is 768 by 768 pixels at 1:1; 1k (the default) is about 1 megapixel, 1.5k about 2, 2k about 4 and 4k about 16 megapixels. The exact width and height vary with the aspect ratio; the area is about the same for every ratio.
• The resolution tier sets the amount billed; the aspect ratio does not: see How Billing Is Measured below.

Example: a wide image at a higher resolution

{
  "prompt": "A quiet harbor town at sunrise, fishing boats and soft mist over the water",
  "aspect_ratio": "21:9",
  "resolution": "2k"
}

Example: a tall image with a fixed seed

{
  "prompt": "A red lighthouse on a rocky cliff at dusk, waves breaking below",
  "aspect_ratio": "9:16",
  "resolution": "1.5k",
  "seed": 1234
}

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing prompt (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'prompt' is required",
  "violations": [
    "'prompt' is required"
  ]
}

A resolution not written exactly as listed (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"768sq\", \"1k\", \"1.5k\", \"2k\", \"4k\" (got \"2K\")",
  "violations": [
    "'resolution' must be one of: \"768sq\", \"1k\", \"1.5k\", \"2k\", \"4k\" (got \"2K\")"
  ]
}

An image sent to text to image (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'image_urls' must be one of:  (got [\"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg\"]); 'image_urls' is not accepted by text to image. Use the FLUX 3 Klein edit API to edit or combine images.",
  "violations": [
    "'image_urls' must be one of:  (got [\"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg\"])",
    "'image_urls' is not accepted by text to image. Use the FLUX 3 Klein edit API to edit or combine images."
  ]
}

More than one image per request (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'num_images' must be one of:  (got 2); 'num_images' is not supported: each request returns one image. Send one request per image.",
  "violations": [
    "'num_images' must be one of:  (got 2)",
    "'num_images' is not supported: each request returns one image. Send one request per image."
  ]
}

image_size from the earlier version of this API (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'image_size' must be one of:  (got \"1k\"); 'image_size' is no longer accepted: FLUX 3 Klein now takes 'aspect_ratio' (for example \"16:9\") and 'resolution' (768sq, 1k, 1.5k, 2k or 4k) instead.",
  "violations": [
    "'image_size' must be one of:  (got \"1k\")",
    "'image_size' is no longer accepted: FLUX 3 Klein now takes 'aspect_ratio' (for example \"16:9\") and 'resolution' (768sq, 1k, 1.5k, 2k or 4k) instead."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the image from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-klein_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-klein_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-klein",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/flux-3-klein/v1/text-to-image.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the image from output.media_url.

How Billing Is Measured

Billing is measured per generated image at the rate for the resolution tier in the request — 1k when you leave it out. Each request generates one image. The aspect ratio, the seed and the prompt do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails. The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-klein-edit/v1/edit-image' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "The same scene as a soft watercolor painting", "image_urls": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"], "aspect_ratio": "auto", "resolution": "1k"}'

Callback Payload (success)

{
  "request_id": "flux-3-klein-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-klein-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Failure callback shape

{
  "request_id": "flux-3-klein-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-klein-edit",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one image. batch_size, num_images, number_of_images, n and count are rejected — send one request per image.
• This API makes still images and has no length setting. duration, seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Send every field at the top level of the JSON body; parameters, input, content and text are rejected.
• Send one to ten images in image_urls, as publicly reachable https URLs (recommended) or base64 data URIs, and refer to them in prompt by their order: the first image, the second image. Each image must be at least 256 pixels on each side and at most 16 megapixels.
• Leave aspect_ratio out (auto) to keep the aspect ratio of the first image, and resolution out for 1k.
• image_url and image are rejected: send the images as a list in image_urls.
• images is not accepted: send the reference images as image_urls (1 to 10 image URLs).
• image_size is no longer accepted: FLUX 3 Klein now takes aspect_ratio (for example "16:9") and resolution (768sq, 1k, 1.5k, 2k or 4k) instead.
• output_format is no longer accepted: the output is always a JPEG image.
• bounding_boxes, enable_prompt_expansion and enable_safety_checker are not supported on this API.
• sync_mode is not supported on this API: requests are asynchronous; poll the status URL for the result.
• Use the JSON types shown: image_urls is a list of strings, prompt, aspect_ratio and resolution are strings, and seed is a whole number. aspect_ratio and resolution take exactly the values listed.
• Omit a field instead of sending null.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.
• stream is not supported: the result is delivered when the job completes.
• Options this API does not offer are rejected: width, height, steps and safety_tolerance.

Images and Size

• Send one to ten images in image_urls and refer to them in prompt by their order. Each image must be at least 256 pixels on each side and at most 16 megapixels.
• aspect_ratio sets the shape of the output: auto, the default, keeps the aspect ratio of the first image; any other value from the list replaces it.
• resolution sets the size, whatever the size of the images you send: 768sq is 768 by 768 pixels at 1:1; 1k (the default) is about 1 megapixel, 1.5k about 2, 2k about 4 and 4k about 16 megapixels. The exact width and height vary with the aspect ratio; the area is about the same for every ratio.
• Only the output image is billed, at the rate for its resolution tier; the images you send are not: see How Billing Is Measured below.

Example: compose two images

{
  "prompt": "The person from the first image standing in the scene of the second image",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "aspect_ratio": "16:9",
  "resolution": "1k"
}

Example: a new shape at a higher resolution

{
  "prompt": "The same photo in a warm evening light",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "aspect_ratio": "3:4",
  "resolution": "2k"
}

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing image_urls (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'image_urls' is required",
  "violations": [
    "'image_urls' is required"
  ]
}

More than 10 images (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'image_urls' must have at most 10 items (got 11)",
  "violations": [
    "'image_urls' must have at most 10 items (got 11)"
  ]
}

An image sent as image_url (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'image_urls' is required; 'image_url' must be one of:  (got \"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg\"); 'image_url' is not accepted. Send the images as 'image_urls': a list of 1 to 10 public URLs or base64 data URIs.",
  "violations": [
    "'image_urls' is required",
    "'image_url' must be one of:  (got \"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg\")",
    "'image_url' is not accepted. Send the images as 'image_urls': a list of 1 to 10 public URLs or base64 data URIs."
  ]
}

image_size from the earlier version of this API (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'image_size' must be one of:  (got \"1k\"); 'image_size' is no longer accepted: FLUX 3 Klein now takes 'aspect_ratio' (for example \"16:9\") and 'resolution' (768sq, 1k, 1.5k, 2k or 4k) instead.",
  "violations": [
    "'image_size' must be one of:  (got \"1k\")",
    "'image_size' is no longer accepted: FLUX 3 Klein now takes 'aspect_ratio' (for example \"16:9\") and 'resolution' (768sq, 1k, 1.5k, 2k or 4k) instead."
  ]
}

More than one image per request (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'num_images' must be one of:  (got 2); 'num_images' is not supported: each request returns one image. Send one request per image.",
  "violations": [
    "'num_images' must be one of:  (got 2)",
    "'num_images' is not supported: each request returns one image. Send one request per image."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the image from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-klein-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-klein-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-klein-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/flux-3-klein-edit/v1/edit-image.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the image from output.media_url.

How Billing Is Measured

Billing is measured per generated image at the rate for the resolution tier in the request — 1k when you leave it out. Each request generates one image. The images you send in image_urls are not billed. The aspect ratio, the seed and the prompt do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails. The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-image/v1/text-to-image' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "A red fox leaping over a stream in a pine forest, low-angle wildlife photograph", "aspect_ratio": "16:9", "resolution": "1k"}'

Callback Payload (success)

{
  "request_id": "flux-3-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-10-03T10:04:54.387Z",
  "completed_at": "2026-10-03 10:05:21"
}

Failure callback shape

{
  "request_id": "flux-3-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-image",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• To edit an image or combine several, use the FLUX 3 Image Edit endpoint; image_urls and image_url are rejected here.
• Each request returns one image. num_images may be left out or set to 1; batch_size, n, count and number_of_images are rejected — send one request per image.
• sync_mode is not supported — a request with sync_mode: true is rejected. The finished image is always delivered as a URL through the status endpoint.
• Values are case-sensitive: use 1k, 2k, 4k — not 1K.
• FLUX 3 Image takes no seed: repeating a request gives a new variation.
• Omit optional fields you do not use — do not send them as null.

Resolution Tiers

resolution sets the approximate pixel count of the output and aspect_ratio sets its shape. Delivered dimensions can differ slightly from the nominal size, because they are rounded to multiples of 16. Higher tiers take longer — 4k can take several minutes. The tier sets the amount billed per image; the aspect ratio does not.

Aspect ratios

auto, 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2. auto (the default) leaves the shape to the model; set a ratio when the shape matters.

Request Headers

Response Handling

Most parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. Problems that need an image to be fetched or the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what to fix. Failed requests are not billed — the hold is released in full.

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the image from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-10-03T10:04:54.387Z",
  "completed_at": "2026-10-03 10:05:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/flux-3-image/v1/text-to-image.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 5–10 seconds, or use a Webhook instead.
4. When status is COMPLETED, download the image from output.media_url.

How billing is measured

Billing is measured per generated image at the rate for the resolution tier in the request — 1k when you leave it out. Each request generates one image. The aspect ratio, output format and prompt expansion do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails.

The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-image-edit/v1/edit-image' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "Replace the background of image 1 with a sunlit beach at golden hour and keep the subject unchanged", "image_urls": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"], "resolution": "1k"}'

Callback Payload (success)

{
  "request_id": "flux-3-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-image-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-10-03T10:04:54.387Z",
  "completed_at": "2026-10-03 10:05:21"
}

Failure callback shape

{
  "request_id": "flux-3-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-image-edit",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Send the images as image_urls, an array, even for a single image; image_url is rejected.
• Image URLs must be https and publicly reachable, or data URIs.
• Each request returns one image. num_images may be left out or set to 1; batch_size, n, count and number_of_images are rejected — send one request per image.
• sync_mode is not supported — a request with sync_mode: true is rejected. The finished image is always delivered as a URL through the status endpoint.
• Values are case-sensitive: use 1k, 2k, 4k — not 1K.
• FLUX 3 Image takes no seed: repeating a request gives a new variation.
• Omit optional fields you do not use — do not send them as null.

Resolution Tiers

resolution sets the approximate pixel count of the output and aspect_ratio sets its shape. Delivered dimensions can differ slightly from the nominal size, because they are rounded to multiples of 16. Higher tiers take longer — 4k can take several minutes. The tier sets the amount billed per image; the aspect ratio does not.

Aspect ratios

auto, 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2. auto (the default) matches the shape of image 1.

Reference Images

• Send 1 to 10 images in image_urls. Order matters: the first is image 1, the second image 2, and so on — refer to them that way in the prompt.
• Precise local edits: send one image and describe only the change; the rest of the image is kept.
• Combining: send several images and say what to take from each — for example the jacket from image 2 on the person in image 1.
• With aspect_ratio: "auto" (the default) the output takes its shape from image 1.
• Each image must be at least 256 pixels on each side and at most 4 megapixels, given as a publicly reachable https URL or a data URI.
• Reference images are not billed separately: the number of images you send does not change the amount.

Example: combine two images

{
  "prompt": "Put the jacket from image 2 on the person in image 1, keeping the pose and background of image 1",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
    "https://your-cdn.example.com/jacket.jpg"
  ],
  "resolution": "1k"
}

Request Headers

Response Handling

Most parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. Problems that need an image to be fetched or the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what to fix. Failed requests are not billed — the hold is released in full.

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the image from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-image-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-10-03T10:04:54.387Z",
  "completed_at": "2026-10-03 10:05:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/flux-3-image-edit/v1/edit-image.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 5–10 seconds, or use a Webhook instead.
4. When status is COMPLETED, download the image from output.media_url.

How billing is measured

Billing is measured per generated image at the rate for the resolution tier in the request — 1k when you leave it out. Each request generates one image. The aspect ratio, output format, prompt expansion and the number of reference images do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails.

The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - Flux Video Upscale generate request

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'flux-video-upscale' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "flux-video-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-video-upscale",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/flux-video-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "flux-video-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-video-upscale",
  "error": null,
  "output": { "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/flux-video-upscale_019dxxxx/output.mp4"], "media_type": "video/mp4" },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request. Video renders take minutes rather than seconds, so a webhook is usually the better fit here.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-video/v1/text-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "A cozy ramen shop on a rainy Tokyo night, steam rising from the broth. Rain patter and quiet kitchen sounds.", "resolution": "hd", "duration": 5}'

Callback Payload (success)

{
  "request_id": "flux-3-video-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-video-text-to-video",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-05T11:20:04.102Z",
  "completed_at": "2026-08-05T11:23:58.870Z"
}

Failure callback shape

{
  "request_id": "flux-3-video-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-video-text-to-video",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Notes

Nothing but a prompt is required. Add aspect_ratio and duration when you need a specific shape or length.

Request Headers

Response Handling

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED (or ERROR), then download output.media_url. A render typically takes a few minutes.

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-video-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-video-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-video-text-to-video",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-05T11:20:04.102Z",
  "completed_at": "2026-08-05T11:23:58.870Z"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Pricing

Billed as a flat price per render, set by the resolution you request. Duration does not change the price — a 20-second clip costs the same as a 5-second one.

Failed requests are not billed.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request. Video renders take minutes rather than seconds, so a webhook is usually the better fit here.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-video/v1/keyframes-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "A cozy ramen shop on a rainy Tokyo night, steam rising from the broth. Rain patter and quiet kitchen sounds.", "keyframes": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/input_model.png", "resolution": "hd", "duration": 5}'

Callback Payload (success)

{
  "request_id": "flux-3-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-video-image-to-video",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-05T11:20:04.102Z",
  "completed_at": "2026-08-05T11:23:58.870Z"
}

Failure callback shape

{
  "request_id": "flux-3-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-video-image-to-video",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Notes

Keyframes may be plain images or [seconds, image] pairs — but not a mix of the two in one request.

Using more than one keyframe

keyframes accepts four shapes. Pick whichever fits — all four are equivalent to the model, they differ only in how much control you take over timing.

1. A single image — the opening frame

The video starts here and the prompt drives the rest.

{
  "prompt": "gentle push in on the scene",
  "keyframes": "https://your-server.com/frame-1.jpg",
  "resolution": "hd",
  "duration": 5
}

2. Two images — start and end

With exactly two untimed images, the first opens the video and the second closes it.

{
  "prompt": "morph smoothly from the first scene to the second",
  "keyframes": [
    "https://your-server.com/frame-1.jpg",
    "https://your-server.com/frame-2.jpg"
  ],
  "resolution": "hd",
  "duration": 5
}

3. Several untimed images — spread evenly

The first opens the video, the last closes it, and the rest fall evenly in between. With three or more untimed images you must also send an explicit whole-number duration — there is no last-pair second for auto to derive the length from.

{
  "prompt": "drift across the scenes",
  "keyframes": [
    "https://your-server.com/frame-1.jpg",
    "https://your-server.com/frame-2.jpg",
    "https://your-server.com/frame-3.jpg",
    "https://your-server.com/frame-4.jpg"
  ],
  "resolution": "hd",
  "duration": 10
}

4. Timed [seconds, image] pairs — exact placement

Pin each image to a second on the timeline. With duration: "auto" the video runs to the last pair's second, rounded up.

{
  "prompt": "drift between the two scenes",
  "keyframes": [
    [
      0,
      "https://your-server.com/frame-1.jpg"
    ],
    [
      4,
      "https://your-server.com/frame-2.jpg"
    ]
  ],
  "resolution": "hd",
  "duration": 5
}

Limits

• Ten keyframes maximum. An eleventh is rejected — that is the model's ceiling, not a gateway restriction.
• Do not mix the two styles. A list must be all plain images or all [seconds, image] pairs, never both in one request.
• Each image is a public https url or a data:image/...;base64 URI. We fetch urls server-side, so they must be reachable from the internet — a signed url is fine, a private one is not.

Request Headers

Response Handling

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED (or ERROR), then download output.media_url. A render typically takes a few minutes.

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-video-image-to-video",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-05T11:20:04.102Z",
  "completed_at": "2026-08-05T11:23:58.870Z"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Pricing

Billed as a flat price per render, set by the resolution you request. Duration does not change the price — a 20-second clip costs the same as a 5-second one.

Failed requests are not billed.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request. Video renders take minutes rather than seconds, so a webhook is usually the better fit here.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/flux-3-video/v1/video-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "the camera pulls back to reveal the whole street", "start_video": "https://your-server.com/clip.mp4", "resolution": "hd", "duration": 5}'

Callback Payload (success)

{
  "request_id": "flux-3-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-video-video-to-video",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-05T11:20:04.102Z",
  "completed_at": "2026-08-05T11:23:58.870Z"
}

Failure callback shape

{
  "request_id": "flux-3-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-3-video-video-to-video",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Notes

The source clip must be 15 seconds or less and 50MB or less. Continuation is priced higher than a fresh render — see Pricing.

Request Headers

Response Handling

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED (or ERROR), then download output.media_url. A render typically takes a few minutes.

curl 'https://gateway.pixazo.ai/v2/requests/status/flux-3-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "flux-3-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-3-video-video-to-video",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-05T11:20:04.102Z",
  "completed_at": "2026-08-05T11:23:58.870Z"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Pricing

Billed as a flat price per render, set by the resolution you request. Duration does not change the price — a 20-second clip costs the same as a 5-second one.

Failed requests are not billed.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - FLUX 2 Max generate request

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'flux-2-max' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "flux-2-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-2-max",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/flux-2-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "flux-2-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-2-max",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/flux-2-max_019dxxxx/output.jpg"],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - FLUX 2 Max Edit generate request

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'flux-2-max-edit' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "flux-2-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-2-max-edit",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/flux-2-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "flux-2-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-2-max-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/flux-2-max-edit_019dxxxx/output.jpeg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - FLUX Pro V1 Virtual Try-On generate request

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'flux-pro-v1-virtual-try-on' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "flux-pro-v1-virtual-try-on_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-pro-v1-virtual-try-on",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/flux-pro-v1-virtual-try-on_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "flux-pro-v1-virtual-try-on_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-pro-v1-virtual-try-on",
  "error": null,
  "output": { "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/flux-pro-v1-virtual-try-on_019dxxxx/output.jpeg"], "media_type": "image/jpeg" },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "flux-2-pro-image-to-image-866_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-2-pro-image-to-image-866",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/flux-2-pro-image-to-image-866_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "flux-2-pro-image-to-image-866_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-2-pro-image-to-image-866",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Generate Request

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'flux-2-pro-image-to-image-866' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "flux-2-pro-image-to-image-866_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "flux-2-pro-image-to-image-866",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/flux-2-pro-image-to-image-866_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "flux-2-pro-image-to-image-866_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "flux-2-pro-image-to-image-866",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/flux-2-pro-image-to-image-866_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR