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 Authorization: Bearer <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 "Authorization: Bearer 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",
    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://api.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()

Example response:

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

The API accepted the job and returned these fields.

Field	Description
job_id	Durable job handle to use when polling the job status endpoint
result_url	Result URL; use it only after job status reaches succeeded

job_id is an opaque identifier. 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 "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 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.

How requests work

Authentication

Image generation requests require an API key with inference access in the Authorization header as a Bearer token.

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

The request examples in this page already include the Bearer token 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:

• Call GET /v1/inference/models.
• Choose a model explicitly.
• Check the model 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 reported by the model catalog:

State	Description
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 supported model can report runtime state: "sleeping". The first request to that model waits in warming while capacity 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

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 "Authorization: Bearer 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 can include a result_url, but this endpoint returns a usable result_url only after the job succeeds.

Job status values:

Status	Description
queued	The request was accepted but has not been assigned to a worker yet
warming	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

Job timing fields:

Field	Description
wait_ms	Customer-visible time before active execution, including queue and warm-up
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.

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 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

For 422 responses, check for a missing model field, unsupported size preset, unsupported strict-mode input image size, or legacy top-level width and height fields.

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

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

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

Field	Required	Description
prompt	Yes	Main generation prompt
model	Yes	Must match a supported model ID
negative_prompt	No	Optional negative guidance
size	No	Object with width and height; must match one supported size preset
steps	No	Defaults to the selected model default
guidance	No	Defaults to the selected model default
seed	No	Optional deterministic seed
input_images_base64	No	Source images for models that accept image input

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.

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.

For input_images_base64, send each source image as raw base64 or as a data URL such as data:image/png;base64,.... Decoded dimensions must match one supported size preset.

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 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.

Read next

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