FLUX 3 Image

API Notes

flux_3_image supports text-to-image generation, single-image editing, and multiple reference images, returning one PNG image per request

flux_3_image is best used with asynchronous creation and polling, especially for 4k or multiple-reference tasks

n does not control the output count; each task still generates one image

Authentication

authorization string required

All APIs require authentication via Bearer Token.

Get API Key:

Visit API Key Management Page to get your API Key.

Usage:

Add to request header:

Authorization: Bearer YOUR_API_KEY

Parameters

Create a task with POST /model/v1/generation. The request body contains model and input, with image parameters in input[0].params.

The examples on the right cover text-to-image generation, single-image editing, and multiple reference images. Replace the reference image example URLs with real image URLs accessible to the service.

model string required

Model ID used for the request

Value: flux_3_image

---

input array required

Input list containing exactly one object

params object required

Image generation or editing parameters

prompt string required

A scene description or instructions for editing reference images. English and Chinese are supported. Reference images are numbered Image 1, Image 2, and so on in input order and can be referenced in the prompt. Layout JSON can be included in the prompt when layout instructions are needed

images string | string[]

Reference images. Omit for text-to-image generation, supply one for single-image editing, or supply multiple in the order referenced by the prompt. Each image can be an accessible HTTP(S) URL, plain Base64, or a data:image/...;base64,... URI. URLs must remain accessible throughout processing

Range: 1-10 images when provided

image string | string[]

Compatibility alias for images. Prefer images and do not send both fields

resolution string

Resolution tier, also used to select the pricing tier. Actual image dimensions vary with aspect ratio and content; a tier does not specify fixed dimensions. Leading and trailing whitespace is removed and the value is normalized to lowercase

Default: 1k

Options: 768sq, 1k, 1.5k, 2k, 4k

aspect_ratio string

Image aspect ratio. With auto, the ratio is chosen from the prompt when there are no reference images, or inherited from the first reference image when references are provided

Default: auto

Options: 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, 9:21, auto

size string

Compatibility size parameter that derives a resolution tier and aspect ratio using the table below. The separators * and × are also accepted. Explicit resolution and aspect_ratio values each take precedence over their derived values. Prefer setting these two parameters directly

response_format string

Image generation result processing format. Both options deliver a platform image URL in output[].content[].url; the unified response does not return a b64_json field to the client

Default: b64_json

Options: b64_json, url

grounding boolean

Whether to allow web and image searches to help interpret the prompt, including prompts about real people, places, or brands. Set to false to disable

Default: true

safety_tolerance integer

Content moderation tolerance; higher values are more permissive

Default: 2

Range: 0-4

size compatibility mapping

size	Derived resolution	Derived aspect_ratio
1024x1024	1k	1:1
1792x1024	1.5k	16:9
2048x2048	2k	1:1

Other size values are accepted only when valid explicit resolution and aspect_ratio values are both provided. Otherwise, task creation returns HTTP 400. An arbitrary size is not assigned a resolution tier based on its pixel area.

For example, sending size=2048x2048, resolution=1k, and aspect_ratio=4:3 executes and prices the request using the 1k tier and the 4:3 aspect ratio.

Polling

Since result generation takes time, you need to poll the task status after creating the task.

The initial response only returns information such as the task ID and initial status. The final result must be obtained by polling the task status endpoint using the task ID.

See the examples on the right for polling requests and responses.

Create with POST /model/v1/generation, then query with GET /model/v1/generation/task/{task_id}. Use the id from the create response in the query path.

A create response with status: "completed" only indicates that the create request has completed. It does not mean that image generation or billing is complete. Continue querying the same task.

Poll approximately every 5 seconds. Continue waiting while the query status is in_progress. Read output[].content[] when the query status is completed and an image result is present. Stop polling and inspect error when the status is failed. If in_queue is returned, keep waiting.

Synchronous requests

POST /model/v1/generation/sync accepts the same request body and waits for the image result. This example generates an image from text:

curl --location 'https://cloud.vtrix.ai/model/v1/generation/sync' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "model": "flux_3_image",
  "input": [
    {
      "params": {
        "prompt": "A pink ceramic cup on a white table, studio photograph",
        "resolution": "768sq",
        "aspect_ratio": "1:1"
      }
    }
  ]
}'

Generation time varies with resolution, reference images, and service load. If the synchronous connection is interrupted, the task may continue in the background and be charged after success. Query the original task if you have its ID; otherwise, check task records or contact support before submitting again to avoid a second generation charge. Use asynchronous creation and polling for long-running tasks.

Response Format

The right-hand panel shows create, processing, and successful query examples. Task IDs, image URLs, and the revised prompt are illustrative. Amounts come from one test and do not represent a fixed quote.

id string

Platform task ID used to query the task

---

created_at integer

Task creation time as a Unix timestamp in milliseconds

---

status string

Task query status. Common values are in_queue, in_progress, completed, and failed. The field in a create response must not be used to determine the final generation result

---

model string

Model ID used for the request

---

output array

A successful query returns one image in output[].content[]

content array

Image content list

type string

Value: image

url string

Platform image download URL. It may include signature parameters; retain the full URL and download the image promptly. Do not assume the URL remains valid indefinitely

size integer

Image file size in bytes, not image dimensions

revised_prompt string

Optional revised prompt used during generation

---

usage object

Usage and pricing information returned by a successful query. Monetary amounts are in USD.

Field	Type	Description
quantity	number	Billing quantity, fixed at 1 image
image_count	integer	Output image count, 1
extra_info.num_images	integer	Image count, 1
unit_price	string	Pricing unit price for the selected resolution tier
cost	string	Calculated task amount; do not treat it as the final charge
payable_amount	string or null	Payable amount read from the platform ledger
charged_amount	string or null	Actual charge read from the platform ledger
user_discount	number	Compatibility field; do not use it to recalculate the final discount. 0 does not mean the task is free
input_tokens / output_tokens / total_tokens	number or null	Billing is per image; these fields are null in the example

payable_amount and charged_amount may be null when ledger data is temporarily unavailable. This does not mean the task is free or uncharged. Query again later and check the platform ledger.

---

error object

Error information for a failed task. Read error.message first and use error.code for troubleshooting if present. Do not make program decisions by matching the illustrative error text

Failed query example:

{
  "id": "task_id",
  "created_at": 1792207683000,
  "status": "failed",
  "model": "flux_3_image",
  "error": {
    "message": "Image generation failed"
  }
}

Error Handling

Scenario	Handling
Invalid resolution or unmapped size	Creation returns HTTP 400; correct the parameters before submitting again
Invalid aspect ratio, moderation parameters, or inaccessible reference image	The task may fail after creation; poll the original task and read error
Image generation or result storage fails	The task becomes failed and no successful-generation fee is charged
Synchronous connection interruption or timeout	Do not infer task failure; check the original task status and ledger first

Billing

Pricing uses the requested resolution tier, with 1 image billed per successful output. If neither resolution nor a size mapping is provided, the tier defaults to 1k.

768sq, 1k, 1.5k, 2k, and 4k are pricing tiers. Actual output dimensions do not change the selected tier. Reference image count and n do not increase the task’s billing quantity. Text-to-image generation, single-image editing, and multiple-reference generation use the same resolution-tier rules.

Failed tasks do not incur a successful-generation fee. An interrupted synchronous connection does not mean the task failed; a task that later succeeds in the background may still be charged.

Prices, exchange rates, and account discounts follow platform configuration. See Pricing. The platform ledger is authoritative for final charges; do not calculate them from cost or user_discount alone.