FLUX 3 Image Generation

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-3-image",
    "prompt": "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
    "aspect_ratio": "21:9",
    "resolution": "2k"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "flux-3-image",
        "prompt": "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
        "aspect_ratio": "21:9",
        "resolution": "2k"
    }
)
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "flux-3-image",
    prompt: "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
    aspect_ratio: "21:9",
    resolution: "2k"
  })
});
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

POST

images

generations

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-3-image",
    "prompt": "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
    "aspect_ratio": "21:9",
    "resolution": "2k"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "flux-3-image",
        "prompt": "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
        "aspect_ratio": "21:9",
        "resolution": "2k"
    }
)
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "flux-3-image",
    prompt: "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
    aspect_ratio: "21:9",
    resolution: "2k"
  })
});
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

This endpoint is asynchronous. A successful submission returns a task_id. Use task queries to retrieve status and images. Stop polling when the status is completed or failed. Generating at 4k may take several minutes; a total wait timeout of 10 minutes is recommended.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-3-image",
    "prompt": "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
    "aspect_ratio": "21:9",
    "resolution": "2k"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "flux-3-image",
        "prompt": "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
        "aspect_ratio": "21:9",
        "resolution": "2k"
    }
)
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "flux-3-image",
    prompt: "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
    aspect_ratio: "21:9",
    resolution: "2k"
  })
});
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

Request headers

string

required

Bearer authentication in the format Bearer <token>, where <token> is your APIMart API Key.

Request parameters

string

required

Must be flux-3-image.

string

required

A scene description for text-to-image, or image editing instructions. Negative prompts are not supported; describe what you want to see instead.Use tags and bbox JSON within prompt to specify layouts or local editing regions. See the examples below.

string[]

Reference image list, up to 10 images. Supports publicly accessible HTTP(S) URLs or Base64 input.Omit for text-to-image. Provide one image for single-image editing or multiple images for multi-image reference.

string

default:"auto"

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, 9:21, or auto.Ratio formats such as 16x9 are also accepted. With auto:

Editing or multiple reference images: follows the aspect ratio of the first reference image.
Text-to-image: determined by the prompt; falls back to 1:1 if no aspect ratio is determined.

string

Compatibility parameter for the aspect ratio. Can replace aspect_ratio and accepts the same values. Use only one of these fields.Pixel dimensions such as 1024x1024 are not supported and return HTTP 400. Use resolution to select the output resolution.

string

default:"1k"

Output resolution tier. Supports 768sq, 1k, 1.5k, 2k, and 4k, case-insensitively. 768 is equivalent to 768sq.This parameter determines the billing tier. If omitted, generation and billing use 1k. Unsupported values such as 3k return HTTP 400.

integer

default:"2"

Content safety tolerance, from 0–4. 0 is the strictest.

boolean

default:"true"

Whether to allow web or image searches before generation. Set to false to disable.Must be a boolean, not the strings "false" or "true".

integer

default:"1"

Each request generates 1 image; only 1 is supported. Submit separate tasks for multiple images. Values above 1 return HTTP 400.

Unsupported parameters

The following parameters return HTTP 400 when provided; they are not silently ignored:

width, height
Pixel dimensions in size, such as 1024x1024
seed, steps, guidance
output_format, negative_prompt, prompt_upsampling, mask_url

Use resolution for higher resolution and aspect_ratio for a specific aspect ratio.

Edit a reference image

{
  "model": "flux-3-image",
  "prompt": "Make the car in the image red while preserving the original road, background, and lighting",
  "image_urls": ["https://example.com/car.jpg"],
  "aspect_ratio": "auto",
  "resolution": "2k"
}

Replace the example URL with a publicly accessible image URL. For multiple references, provide multiple URLs in image_urls, up to 10 images in total.

Multiple reference images

Editing, local editing, and layout use the same endpoint and model on this page, billed by resolution. References are numbered in order: ref_image_0 for the first, ref_image_1 for the second. You can also use Image 1 / Image 2 in the prompt.

{
  "model": "flux-3-image",
  "prompt": "Turn Image 1 into the style of Image 2.",
  "image_urls": [
    "https://example.com/subject.jpg",
    "https://example.com/style.jpg"
  ],
  "aspect_ratio": "auto"
}

Local editing (bounding box)

Start prompt with natural-language editing instructions and refer to elements using <tags>, such as <car_1>. Append a JSON array within the same string, with one object per box. The bbox is not a separate request parameter.

Field	Description
`id`	Matches the element tag in the prompt, without angle brackets.
`from`	Source of the element, such as `ref_image_0`; use `null` for newly drawn or redrawn elements.
`src_bbox`	Box in the source image; must also be `null` when `from` is `null`.
`tgt_bbox`	Box in the output image; matching `src_bbox` keeps the element in place, while a different box moves it.
`desc`	Describes how to change the element or what to preserve.

All box fields (src_bbox, tgt_bbox, bbox) use [top, left, bottom, right], that is, [y1, x1, y2, x2], on a 0–1000 normalized grid: top-left is [0,0] and bottom-right is [1000,1000]. These are not pixel coordinates. This example turns the boxed car red and describes the background to preserve. The URL and box positions are illustrative; replace them to match your image.

{
  "model": "flux-3-image",
  "prompt": "In <ref_image_0>, make the car <car_1> red and preserve the background <background_1>. [{\"id\":\"car_1\",\"from\":null,\"src_bbox\":null,\"tgt_bbox\":[250,300,750,800],\"desc\":\"A red car, preserving its original shape and orientation.\"},{\"id\":\"background_1\",\"from\":\"ref_image_0\",\"src_bbox\":[0,0,1000,1000],\"tgt_bbox\":[0,0,1000,1000],\"desc\":\"Preserve the original road, background, and lighting.\"}]",
  "image_urls": [
    "https://example.com/car.jpg"
  ],
  "aspect_ratio": "auto",
  "resolution": "2k"
}

Move an element

Place the following object in the bbox array at the end of the prompt. from identifies the source image, src_bbox the original position, and tgt_bbox the new position. Also use the matching <knight_1> tag in the natural-language instruction.

{
  "id": "knight_1",
  "from": "ref_image_0",
  "src_bbox": [
    500,
    150,
    850,
    350
  ],
  "tgt_bbox": [
    194,
    55,
    544,
    255
  ],
  "desc": "A miniature grey amigurumi knight figure."
}

Text-to-image layout

Layouts also work without reference images. Each box uses id, bbox, and desc. Set aspect_ratio explicitly because the coordinate grid stretches with the aspect ratio.

{
  "model": "flux-3-image",
  "aspect_ratio": "1:1",
  "prompt": "Minimalist illustration of a black running silhouette <silhouette_1> against a solid chartreuse background <background_1>. [{\"id\":\"background_1\",\"bbox\":[0,0,1000,1000],\"desc\":\"A neon yellow-green background with subtle paper texture.\"},{\"id\":\"silhouette_1\",\"bbox\":[150,150,850,850],\"desc\":\"A black running silhouette with a stippled texture.\"}]"
}

Usage notes

The bbox JSON is part of the prompt string. When writing request JSON manually, escape its internal double quotes as \". SDKs or JSON serialization methods can handle this automatically.
Also list regions that should remain unchanged and describe what to preserve in desc.
Element tags in the prompt must match JSON id values one-to-one. Reference identifiers such as <ref_image_0> point to input images.
This model has no mask parameter and does not support mask_url; providing mask_url returns HTTP 400. Bbox editing does not use a mask upload parameter.

Submission response

integer

Response status code. 200 indicates success.

array

Task submission result.

Show Show task fields

string

submitted indicates successful submission, not completed generation.

string

Task ID used to query task status and results.

Query task results

curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'

Example success response (the image URL is a placeholder):

{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.jpg"]
        }
      ]
    }
  }
}

Read image links from the data.result.images[0].url array. If the task status is failed, inspect the returned error message instead of continuing to wait for an image.

Resolution and billing

Billed per image. The unit price depends only on resolution, not the aspect ratio or number of reference images. Reference images incur no extra charge.

Resolution tier	Approximate output size
`768sq`	About 768×768
`1k` (default)	About 1MP
`1.5k`	About 2MP
`2k`	About 4MP
`4k`	About 16MP

Output sizes are approximate; actual pixel dimensions depend on the returned image. Refer to model pricing for each tier. Tasks that fail or are blocked by content moderation receive a full refund.

Common parameter errors

Request	Result and action
`resolution: "3k"`	HTTP 400; use one of the 5 supported tiers
`size: "1024x1024"`	HTTP 400; use an aspect ratio and select resolution with `resolution`
`n: 2`	HTTP 400; only 1 image is generated per request
11 reference images	HTTP 400; provide at most 10
`grounding: "false"`	HTTP 400; use the boolean `false`

Overview

Models

Text Series

Image Series

Video Series

Audio Series

Moderation Series

Upload Management

Task Management

Account Management

FLUX 3 Image Generation

Request headers

Request parameters

Unsupported parameters

Edit a reference image

Multiple reference images

Local editing (bounding box)

Move an element

Text-to-image layout

Usage notes

Submission response

Query task results

Resolution and billing

Common parameter errors

​Request headers

​Request parameters

​Unsupported parameters

​Edit a reference image

​Multiple reference images

​Local editing (bounding box)

​Move an element

​Text-to-image layout

​Usage notes

​Submission response

​Query task results

​Resolution and billing

​Common parameter errors

Request headers

Request parameters

Unsupported parameters

Edit a reference image

Multiple reference images

Local editing (bounding box)

Move an element

Text-to-image layout

Usage notes

Submission response

Query task results

Resolution and billing

Common parameter errors