FLUX 3 Image API: Text-to-Image & Image Editing

Overview

FLUX 3 Image generates images from text and edits or combines reference images. Each task returns one image. Choose a resolution and output format, submit a task, then poll for the result or receive a webhook callback.

Capability	Value
Model ID	`flux-3-image`
Modes	`text-to-image`, `image-to-image`
Reference images	1-10 URLs for image-to-image
Reference dimensions	Each image must be at least 256 pixels wide and high, and at most 4,000,000 pixels in total
Resolution tiers	`1k`, `2k`, `4k`
Output formats	`jpeg`, `png`
Output	Exactly 1 image URL in the parsed `resultJson.resultUrls` array

Endpoint and authentication

Base URL:

https://api.apixo.ai/api/v1

Method	Endpoint	Purpose
`POST`	`/generateTask/flux-3-image`	Submit an image generation or editing task
`GET`	`/statusTask/flux-3-image?taskId={taskId}`	Query task status and retrieve the result

Include your APIXO API key in every request:

Authorization: Bearer YOUR_API_KEY

Submit requests also require Content-Type: application/json.

Copy-paste async quickstart

Submit a text-to-image task:

curl -X POST "https://api.apixo.ai/api/v1/generateTask/flux-3-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "A white ceramic coffee cup on a wooden table, soft natural daylight",
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "output_format": "png"
    }
  }'

Successful submission:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

Save data.taskId and query the status endpoint. A successful submission means the task was accepted; check data.state to determine the final outcome.

Poll for result

curl "https://api.apixo.ai/api/v1/statusTask/flux-3-image?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

While the task is running, data.state is processing. Continue polling until it becomes success or failed. Success response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://example.com/result.png\"]}",
    "createTime": 1791479211790,
    "completeTime": 1791479234710,
    "costTime": 22920
  }
}

resultJson is a JSON string. Parse it before reading the image URL:

const imageUrl = JSON.parse(response.data.resultJson).resultUrls[0];

Failure response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "UnmappedUpstreamError",
    "failMsg": "The provider rejected the request. Please check your inputs and try again.",
    "createTime": 1791478394190,
    "completeTime": 1791478396181,
    "costTime": 1991
  }
}

A status response with code: 200 can still describe a failed task. Use data.state, failCode, and failMsg to handle task failures.

Image-to-image request

Provide 1-10 reference images in image_urls. Their order is preserved, so refer to them as image 1, image 2, and so on in the prompt.

curl -X POST "https://api.apixo.ai/api/v1/generateTask/flux-3-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "image-to-image",
      "prompt": "Place the product from image 1 into the scene in image 2",
      "image_urls": [
        "https://example.com/product.png",
        "https://example.com/scene.png"
      ],
      "resolution": "1k",
      "output_format": "png"
    }
  }'

Replace the example URLs with public, directly fetchable image URLs. Each reference image must be at least 256 pixels on both sides and contain no more than 4,000,000 pixels (width * height). When aspect_ratio is omitted or blank in image-to-image mode, the output follows the first reference image’s aspect ratio.

Parameters

string

default:"async"

Result delivery mode. Supported values: async, callback. Use async for status polling or callback for webhook delivery.

string

Required when request_type is callback. Provide a public HTTPS endpoint that accepts POST requests. See Webhooks.

object

required

FLUX 3 Image input parameters.

Show properties

string

required

Generation mode. Supported values: text-to-image, image-to-image. This field is required; there is no default mode.

string

required

Non-empty text describing the desired image or edit. Whitespace-only prompts are invalid. For multiple reference images, describe the role of image 1, image 2, and so on. No fixed maximum character count is specified.

string[]

Required for image-to-image. Provide 1-10 public, directly fetchable, non-empty image URLs in reference order. Each image must be at least 256 pixels wide and high, and contain at most 4,000,000 pixels. Use this field only for image-to-image requests.

string

Output aspect ratio. Supported values: 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. When omitted or blank, text-to-image defaults to 1:1; image-to-image follows the first reference image’s ratio.

string

default:"1k"

Output resolution tier. Supported values: 1k, 2k, 4k. Values are case-insensitive. The selected tier determines the price per image.

string

default:"jpeg"

Output image format. Supported values: jpeg, png. Values are case-insensitive.

boolean

default:"false"

Expand the prompt while preserving its intent. Must be a JSON boolean when provided.

Status response fields

All fields below are inside data.

Field	Type	Description
`taskId`	string	Task ID returned by the creation request
`state`	string	`processing`, `success`, or `failed`
`resultJson`	string	Present on success; parse it to read `resultUrls`, an array with exactly one image URL
`createTime`	integer	Creation timestamp in Unix milliseconds
`completeTime`	integer	Completion timestamp in Unix milliseconds, returned for terminal tasks
`costTime`	integer	Task duration in milliseconds, returned for terminal tasks
`failCode`	string	Failure code when `state` is `failed`
`failMsg`	string	Failure explanation when `state` is `failed`

Webhook callback mode

Set request_type to callback and provide callback_url:

{
  "request_type": "callback",
  "callback_url": "https://your-server.com/webhooks/apixo",
  "input": {
    "mode": "text-to-image",
    "prompt": "A minimal coffee shop poster with the title Morning Coffee",
    "resolution": "1k"
  }
}

See Webhooks for receiver setup and delivery handling.

Billing

Both modes generate one image per task and use the same resolution-based prices. The number of reference images does not add a separate charge.

Resolution	APIXO price
`1k`	`$0.05 / image`
`2k`	`$0.12 / image`
`4k`	`$0.65 / image`

See Pricing for current prices.

Latency and polling

Generation time varies with resolution, prompt complexity, reference images, and queue load. A 4K task can take several minutes.

Stage	Guidance
First poll	Wait 10-20 seconds after task creation
Poll interval	Poll every 3-5 seconds while the task is processing
Completion	Stop polling at success or failed; parse resultJson only on success
Production delivery	Use callback mode for high-concurrency workloads and long-running tasks

If a request is rate-limited, reduce concurrency and retry with backoff. Keep the original taskId when querying an accepted task.

Errors and troubleshooting

Check that mode and a non-empty prompt are present.
For image-to-image, provide 1-10 valid reference URLs and respect the per-image dimension and pixel limits.
Use one of the documented aspect ratios, resolution tiers, and output formats.
Inspect data.state even when the status endpoint returns code: 200.
When a task fails, use failCode and failMsg to decide whether to change the input before submitting another task.

See Error Codes for authentication, balance, rate-limit, and task failure handling.

​Overview

​Endpoint and authentication

​Copy-paste async quickstart

​Poll for result

​Image-to-image request

​Parameters

​Status response fields

​Webhook callback mode

​Billing

​Latency and polling

​Errors and troubleshooting

​Related links

Overview

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Image-to-image request

Parameters

Status response fields

Webhook callback mode

Billing

Latency and polling

Errors and troubleshooting

Related links