How to Build a Flux Image Generation Endpoint with a Simple API Call

When your product needs generated images, the hard part is often not the prompt — it is turning a creative model into a predictable backend workflow.

What you can do

The Flux Images Generation API is a single HTTP endpoint for generating or editing images from application code. Instead of building a separate integration for each image model, you send a JSON request with an action, a prompt, a model, and a size, then read the generated image URL from the response.

The documented request shape is:

Base URL: https://api.acedata.cloud
Endpoint: POST /flux/images
Authorization: Bearer <your token>

The same endpoint handles two common workflows:

• action: "generate" for text-to-image generation.
• action: "edit" for editing an existing image through image_url.

For a backend developer, this shape is useful because you can hide provider-specific details behind one small service function. Your UI or job queue can simply say: “generate a product shot,” “make a hero image,” or “edit this uploaded asset,” while your backend owns validation, retries, and callback handling.

How it works

A basic generation request sends a prompt plus a target model and size. The documentation highlights that newer Flux 2 models have stricter size behavior: flux-2-flex, flux-2-pro, and flux-2-max require an image ratio such as 1:1 or 16:9; pixel sizes like 1024x1024 are not accepted for those models.

Here is a minimal curl example using fields from the API guide:

BASE_URL="https://api.acedata.cloud"

curl -X POST "$BASE_URL/flux/images" \
  -H "authorization: Bearer $ACEDATA_API_TOKEN" \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro.",
    "model": "flux-2-pro",
    "size": "1:1"
  }'

A successful response includes a task identifier, a trace identifier, and the image result list:

{
  "success": true,
  "task_id": "5456c749-3bbb-4f10-9eb8-cfbcac297500",
  "trace_id": "ae4eecb8-1dd6-45b4-bfb3-a1c48872536e",
  "data": [
    {
      "image_url": "<generated image URL>"
    }
  ]
}

In production, store task_id and trace_id even when the request succeeds. task_id lets you associate callbacks or later records with the user action that created them. trace_id is what you want in logs when a request fails and you need to debug it without exposing credentials.

Pick the right size format

The size field is where many integrations become fragile. The API guide supports both pixel dimensions and image-ratio strings, but support depends on the selected model.

For flux-dev and flux-pro, the guide lists support for 1024x1024, 1024x1792, 1792x1024, or image ratios. For flux-2-flex, flux-2-pro, flux-2-max, flux-kontext-pro, and flux-kontext-max, the guide lists image-ratio support only.

The documented reference ratios are:

21:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:21

A simple defensive pattern is to validate model and size together before making the request. For example, if your UI offers flux-2-pro, let users choose ratios rather than raw pixels. That keeps your API layer from producing avoidable 400 errors.

Add editing when you already have an image

The same /flux/images endpoint can also edit an image. For editing, set action to edit and provide image_url. The guide lists editing support for flux-dev, flux-pro, flux-kontext-pro, flux-kontext-max, flux-2-flex, flux-2-pro, and flux-2-max.

import requests

base_url = "https://api.acedata.cloud"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "action": "edit",
    "prompt": "a white siamese cat",
    "model": "flux-kontext-pro",
    "image_url": "<source image URL>",
}

response = requests.post(f"{base_url}/flux/images", json=payload, headers=headers)
print(response.text)

That makes it easy to support a second product flow without introducing a second endpoint. For example, you might generate new campaign images from a prompt, but use edit mode when a user uploads an existing product photo and asks for a different style.

Use callbacks for longer jobs

Image generation can take about one to two minutes. If you keep every request open until completion, you may tie up web workers or hit infrastructure timeouts. The API supports asynchronous callbacks with callback_url.

In callback mode, your request includes the callback URL, the API immediately returns a task_id, and the final result is sent to your server as POST JSON when the task completes.

{
  "callback_url": "https://example.com/webhooks/flux-images"
}

The guide’s callback result includes success, task_id, trace_id, and data, where each generated item can include fields such as prompt, image_url, seed, and timings.

For a real app, create a database row before calling the API, store it with status queued, then update it when the callback arrives with the matching task_id. Your frontend can poll your own backend, not the image provider directly.

Error handling checklist

The documented error categories are straightforward:

• 400 token_mismatched: missing or invalid parameters.
• 400 api_not_implemented: missing or invalid parameters.
• 401 invalid_token: invalid or missing authorization token.
• 429 too_many_requests: request rate exceeded.
• 500 api_error: server-side failure.

An error response can look like this:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

The practical takeaway: log the trace_id, return a safe message to the user, and never log the bearer token.

A small production wrapper

My preferred implementation is a thin wrapper with four responsibilities: validate action, validate model plus size, submit the request, and persist task_id / trace_id / data[].image_url. That is enough to make image generation feel like a normal backend capability instead of a one-off demo script.

For the complete parameter reference and examples, see the Ace Data Cloud Flux Images Generation API guide.