Image

Use the Image API when you want to generate images from your own application, script, or automation.

RemoteGPU does not choose a default model for you. Every request must name the model it should run against.

Send requests

Quickstart text-to-image

For your first call, start with a text-only model and the minimum required fields: prompt and model.

Before you send it:

• Create an API key with inference access
• Send that key in the x-api-key header
• Name the model explicitly

If you have not created a key yet, read API keys first.

curl

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

JavaScript

const response = await fetch("https://api.remotegpu.ai/v1/inference/image", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": 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://api.remotegpu.ai/v1/inference/image",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["REMOTEGPU_API_KEY"],
    },
    json={
        "prompt": "YOUR_PROMPT",
        "model": "black-forest-labs/FLUX.1-dev"
    },
    timeout=60,
)
response.raise_for_status()

Example response:

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

This response means the job was accepted.

• job_id is the durable handle for the job. Poll the job status endpoint with it
• result_url may be included immediately as a convenience, but do not treat it as ready until job status reaches succeeded

job_id is an opaque identifier. The current format is UUID v4, but clients should store and forward it exactly as returned instead of parsing or validating a specific shape.

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.

curl -X POST "https://api.remotegpu.ai/v1/inference/image" \
  -H "Content-Type: application/json" \
  -H "x-api-key: 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 already match one of the supported size presets or the API returns 422. If your source image has arbitrary dimensions, resize and crop it in your client before sending the request.

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

Decide if this API fits

Use the Image API for:

• image generation from applications, backends, scripts, or automations
• programmatic control over prompts and model selection
• image generation workflows that do not need Kubernetes resources

Use Comfy when you want a hosted workspace in the console. Use Kubernetes when you want to run and expose your own workloads in a namespace.

The matching console page is Inference API / Image.

How requests work

Authentication

Image generation requests require an API key with inference access in the x-api-key header.

Create an Inference key in API keys, then send it on every request.

The request examples in this page already include the x-api-key header.

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

Every request must name a supported model. RemoteGPU does not choose a default model for you.

Before you build a client flow:

• Read GET /v1/inference/models
• Choose a model explicitly
• Check the model's current runtime state
• Keep your prompt and input image count within the selected model's limits

The model catalog is public. Job status requires an inference-enabled API key.

Runtime states:

State	Meaning
ready	At least one worker is ready to serve requests
starting	Capacity is starting or warming
sleeping	No warm worker is available for that model

A model can be supported even when its runtime state is sleeping. In that case, the first request may spend time in warming before it starts running.

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

The image API returns a job_id. Use that ID to poll job status until the job reaches a terminal state.

Job status example

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

Example response:

{
  "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
}

This response is polling-safe and intentionally lightweight. It reports status and runtime timing, but does not embed large result payloads.

Use the job status response as the source of truth for readiness. The enqueue response may include a result_url, but this endpoint only returns a usable result_url after the job succeeds.

Status values:

• queued: the request was accepted but has not been assigned to a worker yet
• warming: the job has been accepted and worker capacity is being acquired or prepared
• running: a worker has started execution
• succeeded: the image finished successfully
• failed: the job finished with an error
• cancelled: the job was cancelled before completion

Timing fields:

• wait_ms: all customer-visible time before active execution begins, including queue delay, warming, and scale-up time
• run_ms: active execution time after the job enters running

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

result_url is returned once the job reaches succeeded. Only successful jobs should expose a usable result URL.

Common status codes

Status code	Meaning
401	Missing, invalid, revoked, or expired API key
403	API key is valid but not authorized for inference APIs
422	Request validation failed, such as a missing model field, unsupported size preset, unsupported strict-mode input image size, or legacy width / height request fields
400	The request body is syntactically valid JSON but the payload is invalid for the selected model or endpoint
503	The selected model exists but is unavailable for serving

Reference

Current 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

RemoteGPU accepts a fixed set of image size presets. If you send a size object outside this set, the API returns 422.

The same preset list also applies to input_images_base64. Each source image must use one of these size presets before you call the API.

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

Field	Required	Notes
prompt	Yes	Main generation prompt
model	Yes	Must match a supported model ID
negative_prompt	No	Optional negative guidance. Send this only if the selected model supports it
size	No	Object with width and height; defaults to the selected model default and must match one supported size preset
steps	No	Defaults to the selected model default
guidance	No	Defaults to the selected model default. Some models use a fixed value
seed	No	Optional deterministic seed
input_images_base64	No	Use only with models that accept source images. Send each image as raw base64 or as a data URL such as data:image/png;base64,...; decoded dimensions must match one supported size preset

If model is omitted, the request is rejected. If the selected model is known but unavailable for serving, the API returns 503.

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

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.

Legacy top-level width and height request fields are rejected.

Requests that include the retired remove_bg field are rejected.

Model catalog endpoint

Use the catalog endpoint when you need the full model field details instead of the summarized table above.

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

The response includes:

• image[].model: the model identifier to send in POST /v1/inference/image
• image[].parameters: the public field details, 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: the current serving state
• image[].recent_summary_stats: recent wait, run, and total time summaries

Prefer reading this endpoint over hardcoding per-model limits in clients.

Recommended client flow

1. Read GET /v1/inference/models to choose a supported model and inspect its limits, defaults, supported sizes, and current runtime state
2. Submit POST /v1/inference/image with an explicit model
3. Poll GET /v1/inference/jobs/{job_id} until the job reaches a terminal state: succeeded, failed, or cancelled

Runtime status in the console

The Inference API / Image page in the console shows:

• model identifier
• status
• minimum and maximum image inputs
• prompt limit

Read next

• Read API keys to create or rotate inference keys.
• Read Inference API overview to compare the API with hosted applications and Kubernetes.