Image

Generate images from your application or script with the Image API. Send a prompt and a model ID, then use the returned job ID to check when your image is ready.

Send requests

Quickstart text-to-image

Start with a model that generates images from text. The required fields are prompt, which describes the image, and model, which selects the model.

Create a key with Token Factory access using API keys, and send it in the Authorization: Bearer <api-key> header.

curlJavaScriptPython

bash

curl -X POST "https://inference.remotegpu.ai/v1/inference/image" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "YOUR_PROMPT",
    "model": "black-forest-labs/FLUX.1-dev"
  }'

const response = await fetch(
  "https://inference.remotegpu.ai/v1/inference/image",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.REMOTEGPU_API_KEY}`,
    },
    body: JSON.stringify({
      prompt: "YOUR_PROMPT",
      model: "black-forest-labs/FLUX.1-dev",
    }),
  },
);

python

import os
import requests

response = requests.post(
    "https://inference.remotegpu.ai/v1/inference/image",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['REMOTEGPU_API_KEY']}",
    },
    json={
        "prompt": "YOUR_PROMPT",
        "model": "black-forest-labs/FLUX.1-dev"
    },
    timeout=60,
)
response.raise_for_status()

Replace YOUR_PROMPT with your image description and YOUR_API_KEY with your key. For JavaScript or Python, set REMOTEGPU_API_KEY in the environment where the code runs.

An accepted request returns a response like this:

json

{
  "job_id": "c3b1e0e7-2f7c-4c66-bd13-97b6c2b87f1d",
  "job_type": "image",
  "result_url": "https://..."
}

Save these fields so you can check the job and download the finished image:

Field	Description
`job_id`	The ID to use when checking this job's status
`result_url`	Result URL; use it only after job status reaches `succeeded`

Keep job_id exactly as returned. Your code should not depend on its format or try to interpret parts of it.

Image-to-image example

Use a model that accepts input images when you send source images. The example below uses black-forest-labs/FLUX.1-Kontext-dev, which requires exactly one source image.

bash

curl -X POST "https://inference.remotegpu.ai/v1/inference/image" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "YOUR_PROMPT",
    "model": "black-forest-labs/FLUX.1-Kontext-dev",
    "size": {
      "width": 1024,
      "height": 1024
    },
    "input_images_base64": [
      "BASE64_ENCODED_IMAGE"
    ]
  }'

Replace BASE64_ENCODED_IMAGE with raw base64 or a data URL.

Each input image must have one of the supported sizes or the API returns 422. Resize and crop an image to a supported size before sending it.

If input image data fails validation, the API returns 400.

How requests work

Authentication

Send a Token Factory key in the Authorization header as a Bearer token on every generation request. You can create or replace a key in API keys.

If the key is missing or invalid, the API returns 401. If the key is valid but does not allow inference APIs, the API returns 403.

Choose a model first

Call GET /v1/inference/models to choose a model ID. Check whether the model is ready, how long the prompt can be, and how many input images it accepts before sending your request.

You can read the model catalog without a key. To check a job's status, you need a key with Token Factory access.

The catalog uses these states to show whether a model is ready:

State	Description
`ready`	Ready to serve requests
`starting`	The model is starting
`sleeping`	The model needs to start before serving requests

If a model reports state: "sleeping", the first request waits in warming while the model starts.

Source images

For input_images_base64:

Send raw base64 or a data URL such as data:image/png;base64,....
The API validates that each item decodes to an image.
Source images must not exceed 8192px on either axis.
Each decoded image must match one supported size preset for the selected model.

Check job status

Use the job_id from your request to check its status repeatedly. Stop checking when the status is succeeded, failed, or cancelled.

Job status example

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://inference.remotegpu.ai/v1/inference/jobs/c3b1e0e7-2f7c-4c66-bd13-97b6c2b87f1d"

Example response:

json

{
  "job_id": "c3b1e0e7-2f7c-4c66-bd13-97b6c2b87f1d",
  "job_type": "image",
  "model": "black-forest-labs/FLUX.2-dev",
  "status": "running",
  "created_at": "2026-03-30T07:00:00Z",
  "updated_at": "2026-03-30T07:00:42Z",
  "started_at": "2026-03-30T07:00:12Z",
  "completed_at": null,
  "wait_ms": 12000,
  "run_ms": 30000,
  "result_url": null,
  "error_message": null
}

Replace the example job ID in the URL with your own. A generation request can return a result_url before the image exists, so check the job status before downloading. Once the job succeeds, this status endpoint returns the usable result_url. If it fails, read error_message.

Job status values:

Status	Description
`queued`	The request was accepted and is waiting to start
`warming`	The model is preparing to serve the request
`running`	Image generation is in progress
`succeeded`	The image finished successfully
`failed`	The job finished with an error
`cancelled`	The job was cancelled before completion

Job timing fields:

Field	Description
`wait_ms`	Time in milliseconds spent waiting in the queue and waiting for the model to start
`run_ms`	Time in milliseconds spent generating after the job enters `running`

Jobs that have not entered running yet report run_ms as 0.

Common status codes

Status code	Description
`401`	Missing, invalid, revoked, or expired API key
`403`	API key is valid but not authorized for inference APIs
`422`	Request validation failed
`400`	The JSON can be read, but its values are not valid for this model or endpoint
`503`	The model exists but cannot serve requests
`500`	A server error prevented the request from completing

For 422 responses, check the required fields and supported image sizes. Set output dimensions in size.width and size.height.

Reference

Image models

FLUX.1 models

Model	Min images	Max images	Max prompt length	Default parameters
`black-forest-labs/FLUX.1-schnell`	0	0	1024 chars	`512x512`, `4` steps, guidance `0`
`black-forest-labs/FLUX.1-Kontext-dev`	1	1	2048 chars	`512x512`, `30` steps, guidance `3.5`
`black-forest-labs/FLUX.1-dev`	0	0	2048 chars	`512x512`, `30` steps, guidance `3.5`

FLUX.2 models

Model	Min images	Max images	Max prompt length	Default parameters
`black-forest-labs/FLUX.2-klein-9B`	0	4	2048 chars	`1024x1024`, `4` steps, guidance `1`
`black-forest-labs/FLUX.2-dev`	0	6	4096 chars	`512x512`, `30` steps, guidance `4`

Supported image sizes

Choose one of the image sizes below. The API returns 422 if the size you request is not in this list.

Images in input_images_base64 must also match a size in this list. Resize source images before sending them if needed.

Aspect ratio	Supported sizes
`1:1`	`512x512`, `1024x1024`, `2048x2048`
`4:3`	`1024x768`, `1536x1152`, `2048x1536`
`3:4`	`768x1024`, `1152x1536`, `1536x2048`
`16:9`	`1280x720`, `1536x864`, `2048x1152`
`9:16`	`720x1280`, `864x1536`, `1152x2048`

If you omit size, RemoteGPU applies the selected model default.

Request body fields

Supported fields for POST /v1/inference/image requests:

Field	Required	Description
`prompt`	Yes	Description of the image you want
`model`	Yes	Must match a supported model ID
`negative_prompt`	No	What to avoid in the generated image, if the model supports it
`size`	No	Object with `width` and `height`; must match one supported size preset
`steps`	No	Uses the model's default when omitted
`guidance`	No	Defaults to the selected model default
`seed`	No	Seed for repeating generation with the same settings
`input_images_base64`	No	Source images for models that accept image input

If you omit size, steps, or guidance, RemoteGPU applies the selected model's defaults.

Optional fields vary by model. For example, some models do not support negative_prompt, and some use a fixed guidance value. Check GET /v1/inference/models before sending optional fields.

Model catalog endpoint

Request the model catalog to see each model's supported parameters, defaults, and limits:

bash

curl "https://inference.remotegpu.ai/v1/inference/models"

The response includes:

image[].model: the model identifier to send in POST /v1/inference/image
image[].parameters: supported request settings, including defaults, limits, and allowed values
image[].parameters.input_images: the source image count limits for that model. In the request body, send the images in input_images_base64
image[].runtime.state: whether the model is ready, starting, or sleeping
image[].recent_summary_stats: recent times spent waiting, generating, and completing jobs

Read these limits from the catalog so your client can use them without a code change when a model's limits change.

Image ​

Send requests ​

Quickstart text-to-image ​

Image-to-image example ​

How requests work ​

Authentication ​

Choose a model first ​

Source images ​

Check job status ​

Job status example ​

Common status codes ​

Reference ​

Image models ​

FLUX.1 models ​

FLUX.2 models ​

Supported image sizes ​

Request body fields ​

Model catalog endpoint ​

Read next ​

Image

Send requests

Quickstart text-to-image

Image-to-image example

How requests work

Authentication

Choose a model first

Source images

Check job status

Job status example

Common status codes

Reference

Image models

FLUX.1 models

FLUX.2 models

Supported image sizes

Request body fields

Model catalog endpoint

Read next