Image inference

RemoteGPU image generation uses explicit model selection. The API does not pick a default model on your behalf, so every request must name the model it should run against.

Authentication

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

curl -X POST "https://api.remotegpu.ai/v1/inference/image" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "a cinematic portrait of an astronaut cat",
    "model": "black-forest-labs/FLUX.2-dev",
    "width": 768,
    "height": 768,
    "steps": 28,
    "guidance": 4.0
  }'

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.

Before you send requests

• Choose a model explicitly
• Confirm that the model is currently serving
• Keep your prompt and input image count within the selected model's limits

Two read-only endpoints help with this:

• GET /v1/inference/models Returns the supported model catalog and each model's limits
• GET /v1/inference/runtime/models Returns current serving state, including available, ready_replicas, and desired_replicas

These catalog endpoints are public and do not require x-api-key.

Current image models

Model	Min images	Max images	Max prompt length	Default parameters
black-forest-labs/FLUX.1-dev	0	0	2048 chars	512x512, 30 steps, guidance 3.5
black-forest-labs/FLUX.2-dev	0	10	4096 chars	512x512, 30 steps, guidance 4.0

Request contract

• prompt
• model

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

Common optional fields:

• negative_prompt
• width
• height
• steps
• guidance
• seed
• input_images_base64

The request payload is merged with the selected model's parameter_defaults. If you omit width, height, steps, or guidance, the model defaults are applied automatically.

Requests that include the retired remove_bg field are rejected.

Text-to-image example

Use a model with min_input_images = 0 when you are not sending source images.

curl -X POST "https://api.remotegpu.ai/v1/inference/image" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/FLUX.1-dev",
    "prompt": "a cinematic portrait of an astronaut cat",
    "width": 768,
    "height": 768
  }'

Example response:

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

job_id is an opaque identifier for the enqueued job. 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 input_images_base64 when the selected model accepts input images.

curl -X POST "https://api.remotegpu.ai/v1/inference/image" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/FLUX.2-dev",
    "prompt": "turn this product photo into a soft studio render",
    "input_images_base64": [
      "BASE64_ENCODED_IMAGE"
    ]
  }'

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

Runtime status example

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

Example response:

{
  "image": [
    {
      "model": "black-forest-labs/FLUX.1-dev",
      "available": true,
      "ready_replicas": 1,
      "desired_replicas": 1
    },
    {
      "model": "black-forest-labs/FLUX.2-dev",
      "available": true,
      "ready_replicas": 1,
      "desired_replicas": 1
    }
  ]
}

Common status codes

• 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
• 400 The selected model does not support the requested prompt length or image count, or an input image failed validation
• 503 The selected model is known but is not currently serving

Recommended client flow

1. Read GET /v1/inference/models to learn limits and defaults
2. Read GET /v1/inference/runtime/models to see what is currently serving
3. Submit POST /v1/inference/image with an explicit model

Runtime status in the console

The console Inference API / Image page shows:

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