Flux AI API Reference

Welcome to the Flux AI API, a unified gateway for advanced AI image generation models. This guide provides all the information you need to integrate our powerful image generation capabilities into your applications.

Authentication

All API requests must be authenticated using a Bearer Token. You must include an Authorization header with every request.

Header:

Authorization: Bearer YOUR_API_KEY

You can generate and manage your API keys from your account dashboard.

Endpoints

POST

/v1/images/generations

Start an Image Generation Task

This asynchronous endpoint initiates a new image generation or editing task. It immediately returns a taskId which you will use to poll for the final result.

Request Body

Parameter	Type	Required	Description
`prompt`	string	Yes	A detailed English description of the desired image or the edits to be made.
`model`	string	Yes	The specific model to use for the generation. See the "Supported Models" section below.
`aspect_ratio`	string	No	The aspect ratio of the output image (e.g., "16:9", "1:1", "9:16").
`input_image`	string	No	A URL to a publicly accessible image. Providing this switches to "image-to-image" mode.
`enable_translation`	boolean	No	Set to true to enable automatic translation if prompt is not in English.

Supported Models

Flux Models:
flux-kontext-pro
flux-kontext-max
GPT-4o Models:
gpt-4o
(aspect_ratio limited to "1:1", "3:2", "2:3")

Example Request (cURL)

curl --location 'https://api.flux-context.org/v1/images/generations' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "A majestic lion wearing a golden crown, photorealistic style",
    "model": "flux-kontext-pro",
    "aspect_ratio": "16:9"
}'

Success Response (202 Accepted)

The server accepts your request and begins processing.

Parameter	Type	Description
`taskId`	string	The unique ID for this task. Save this to query its status.
`status`	string	Will always be "processing" on initial request.
`creditsCharged`	integer	The number of credits deducted for this operation.

{
  "taskId": "9a6da945-e7e6-4ad9-ab59-52c4e378bd65",
  "status": "processing",
  "creditsCharged": 10
}

Error Responses

Status Code	Meaning	Example Reason
400	Bad Request	Missing required field or invalid value
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient credits
500	Internal Server Error	Server problem, try again later
503	Service Unavailable	Model service not configured

Example 402 Error Body:

{
    "error": "Insufficient credits",
    "creditsRequired": 10,
    "creditsAvailable": 5
}

GET

/v1/images/generations/[taskId]

Check Task Status and Get Result

Poll this endpoint using the taskId from the previous step to check the task's progress and retrieve the final image URL once completed.

Example Request (cURL)

curl --location 'https://api.flux-context.org/v1/images/generations/9a6da945-e7e6-4ad9-ab59-52c4e378bd65' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response Body

Parameter	Type	Description
`status`	string	Current state: "processing", "completed", or "failed"
`result`	object	Only present if status is "completed"
`result.url`	string	URL to the generated image (valid for 14 days)
`error`	string	Only present if status is "failed"

Example Responses

While Processing:

{
  "status": "processing"
}

When Completed Successfully:

{
  "status": "completed",
  "result": {
    "url": "https://storage.provider.com/path/to/generated_image.png"
  }
}

When Failed:

{
  "status": "failed",
  "error": "The prompt was rejected by the safety system."
}

Typical Workflow

POST to /v1/images/generations with your prompt and parameters.
Receive a
202 Accepted
response containing a taskId.
GET from /v1/images/generations/[taskId] periodically (e.g., every 5-10 seconds).
Continue polling until the status changes from processing to either completed or failed.
If completed, retrieve the image URL from the result.url field.

Need help? Contact our support team or check our developer community.