​
Images API

TokenFlux exposes a unified image generation surface that fronts multiple visual model providers. Every request uses a canonical model ID and a structured input payload that is validated against the model’s JSON schema before reaching the upstream provider. Responses share a consistent shape regardless of the backing service, making it easy to build tooling around job creation, polling, and history management.

​
Available endpoints

MethodPathAuth?Description
GET/v1/images/modelsNoList all enabled image models with pricing and JSON schemas.
POST/v1/images/generationsYesStart a new asynchronous image generation job.
GET/v1/images/generationsYesRetrieve your most recent successful generations (up to 100).
GET/v1/images/generations/{id}YesPoll the status and outputs for a specific generation.
All authenticated endpoints accept API keys in Authorization: Bearer or X-Api-Key headers via the shared authentication middleware. Requests are rejected with 403 Forbidden when the caller has less than 0.01 credits remaining.

​
List image models

​
Endpoint

GET /v1/images/models

​
Response

The endpoint returns a JSONResult envelope with a data array of model descriptors. TokenFlux caches the list for 24 hours in memory so you can safely cache it in clients as well. Each entry includes:
FieldTypeDescription
idstringCanonical model ID to use in generation requests.
namestringHuman-readable model name.
model_providerstringUpstream provider (for example black-forest-labs, google).
descriptionstringShort description of the model’s strengths.
tagsarrayProvider-defined tags such as text-to-image.
pricingobjectCost metadata with price, currency, and unit fields.
input_schemaobjectJSON Schema describing the required input payload.
{
  "success": true,
  "code": 200,
  "data": [
    {
      "id": "black-forest-labs/flux-schnell",
      "name": "FLUX.1 [schnell]",
      "model_provider": "black-forest-labs",
      "description": "The fastest image generation model tailored for local development and personal use",
      "tags": ["text-to-image"],
      "pricing": { "price": 0.025, "currency": "USD", "unit": 1 },
      "input_schema": {
        "properties": {
          "prompt": { "type": "string", "description": "Prompt for generated image" },
          "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "21:9", "3:2"] }
        }
      }
    }
  ]
}

​
Create image generation

​
Endpoint

POST /v1/images/generations

​
Request body

FieldTypeRequiredDescription
modelstringYesCanonical model ID from /v1/images/models.
inputobjectYesProvider-specific payload that must satisfy the model’s JSON schema. For example, flux-schnell expects prompt, aspect_ratio, num_outputs, and other tuning parameters.
webhookstringNoOptional URL to receive provider callbacks when supported. Currently stored for future use.
Invalid payloads return 400 Bad Request with a descriptive validation error message.

​
Response

The endpoint returns the newly created job wrapped in a JSONResult. The status is usually starting immediately after creation. Use the job id to poll until the status becomes succeeded or failed. 
{
  "success": true,
  "code": 200,
  "data": {
    "id": "0a4c1d62-2cd0-4cf1-9e0c-1b2f7f4f5678",
    "model": "black-forest-labs/flux-schnell",
    "status": "starting"
  }
}

​
Get a generation

​
Endpoint

GET /v1/images/generations/{id}

​
Behavior

  • Looks up the generation in the database and, if the job is still starting or processing, refreshes the status and image list by querying the upstream provider.
  • Persists provider responses (including image URLs and costs) before returning the unified data payload.

​
Response

{
  "success": true,
  "code": 200,
  "data": {
    "id": "0a4c1d62-2cd0-4cf1-9e0c-1b2f7f4f5678",
    "model": "black-forest-labs/flux-schnell",
    "status": "succeeded",
    "cost": 0.05,
    "images": [
      {
        "url": "https://replicate.delivery/pbxt/abc123.png"
      }
    ]
  }
}

​
Status values

StatusMeaning
startingJob was accepted and queued with the provider.
processingProvider is still generating results. Poll again or wait for a webhook.
succeededImages are available in the images array.
failedProvider reported an error; error contains details.
canceledJob was canceled (not currently issued by providers, reserved for future use).

​
List recent generations

​
Endpoint

GET /v1/images/generations

​
Response

Returns up to 100 successful generations for the authenticated user ordered by created_at DESC. In-progress or failed jobs are excluded from this list. Use the individual GET /{id} endpoint to inspect pending jobs. 
{
  "success": true,
  "code": 200,
  "data": [
    {
      "id": "0a4c1d62-2cd0-4cf1-9e0c-1b2f7f4f5678",
      "model": "black-forest-labs/flux-schnell",
      "status": "succeeded",
      "cost": 0.05,
      "images": [
        { "url": "https://replicate.delivery/pbxt/abc123.png" },
        { "url": "https://replicate.delivery/pbxt/def456.png" }
      ]
    }
  ]
}

​
Data model

Each response’s data field conforms to the following structure.
FieldTypeDescription
idstringUUID of the generation.
modelstringCanonical model ID.
statusstringOne of the status values above.
imagesarrayZero or more Image objects. Present when the provider returns image URLs or base64 data.
costnumberTotal credits consumed for the job. Set when images are available.
errorstringHuman-readable error message when status is failed.
Image objects provide:
FieldTypeDescription
urlstringProvider-hosted URL to download the image.
datastringBase64 data when the provider returns inline bytes.
context_typestringMIME type of the inline data (for example image/png).
widthintegerImage width in pixels, when reported.
heightintegerImage height in pixels, when reported.

​
Error handling

StatusWhen it occursBody
400 Bad RequestSchema validation fails or required parameters are missing.{ "success": false, "code": 400, "message": "input validation failed" }
403 ForbiddenAccount quota below 0.01 credits.{ "success": false, "code": 403, "message": "insufficient quota" }
404 Not FoundGeneration ID does not exist for the current user.{ "success": false, "code": 404, "message": "missing ID parameter" }
500 Internal Server ErrorProvider call failed or TokenFlux could not persist results.{ "success": false, "code": 500, "message": "internal server error" }

​
Usage tips

  • TokenFlux stores every request’s original input and provider response, so you can safely replay generations or audit output costs later.
  • The optional webhook URL is persisted and ready for future asynchronous callback support. Until then, poll GET /v1/images/generations/{id} for job completion.
  • Pair this API with the Chat Completions API to build multimodal assistants that mix text and image generation.