✦ DEVELOPER

API reference

A small OpenAI-compatible image API. Change the base URL and API key, then use the image generation endpoint you already know.

Capabilities follow each modelModels, prices, ratios, output tiers, and reference-image support come from the active provider configuration.

Base information

Base URL

AuthenticationAuthorization: Bearer <key>

Retry safetyIdempotency-Key: <unique-id>

API keyYOUR_API_KEY

Idempotency-Key is supported by both image generation and image edit requests.

No key yet? Generate one in Account → API key.

Endpoints

GET/v1/modelsList models

GET/v1/user/balanceGet balance

POST/v1/images/generationsCreate images

POST/v1/images/editsEdit from references

POST/v1/videosCreate video job

GET/v1/videos/{id}Get video status

GET/v1/videos/{id}/contentDownload video

Quickstart

Your first request only needs a model, a prompt, and your API key.

cURL

curl /images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: image-request-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MonaLisa-v1",
    "prompt": "a quiet glass house beside a lake at dawn",
    "size": "1024x1024",
    "n": 1
  }'

Model and pricing

The values below are read from this server, so the docs stay in sync with the active channel.

Loading current model…

Request body

POST /v1/images/generations

Field	Type	Required	Description
`model`	string	Yes	Public model ID returned by /v1/models.
`prompt`	string	Yes	What you want to see, up to 8,000 characters.
`size`	string	No	A published width×height value. When omitted, the model's default size is used; legacy values without quality are mapped to the closest supported tier.
`quality`	string	No	One of the quality IDs published by the model. It is billed independently from size.
`n`	integer	No	Number of images, from 1 to 4, default 1.

Recommended size values

1:11024x1024

3:21200x800

16:91280x720

2:3800x1200

9:16720x1280

Use a unique Idempotency-Key for each logical generation. Retrying the same body with the same key returns the saved result without charging or calling the provider again; reusing it with different parameters returns HTTP 409.

Use GET /v1/models first. The administrator controls which public model IDs are available; pricing and provider mappings remain server-side.

Image edits with reference files

Field	Type	Required	Description
`model`	string	Yes	A public model marked with reference-image support below.
`prompt`	string	Yes	Editing instructions, up to 8,000 characters.
`image`	file, repeatable	Yes	One or more bitmap reference files. Repeat the image field up to the model limit.
`size`	string	No	Requested output size. Default: 1024x1024.

Send multipart/form-data. This endpoint creates one output image and does not accept n. Use a unique Idempotency-Key for each logical edit; retrying with the same fields and identical reference files reuses the completed result without another charge, while changing any input returns HTTP 409.

cURL · multipart/form-data

Generation lifecycle

The Studio tracks queued and processing jobs until the active provider returns a final result.

Queue and progressQueued, processing, partial, completed, failed, and cancelled states stay visible in the Studio.

CancelQueued work is cancelled immediately and refunded. Work that already started follows the upstream charged state.

Durable recoveryAccepted asynchronous tasks are reconciled after browser reconnects or service restarts without submitting them twice.

Live preview frames and upstream session resume are shown only when an active provider supports them. Standard and asynchronous OpenAI-compatible routes still expose queue and task progress.

Platform limits and configuration

These values describe the live service contract, not a browser timeout.

Image concurrencyLoading runtime capacity…

Persistent queueLoading queue limit…

Preview and retentionPreview links expire after 30 minutes. Finished files remain downloadable for 7 days, then cleanup removes them.

Three Epay routesAdministrators can configure up to three encrypted Epay gateways. Enabled routes are selected by payment method and priority; merchant secrets never reach the browser.

Resolution mapping example

Paste this JSON into the model's Provider sizes field in the admin console. The public Studio then shows only sizes valid for the selected ratio and tier.

size_map

{
  "1:1": {
    "low": "1024x1024",
    "medium": "2048x2048",
    "high": "4096x4096"
  },
  "16:9": {
    "low": "1536x864",
    "medium": "2048x1152",
    "high": "4096x2304"
  }
}

Use the exact quality IDs configured for that model. A size is accepted only when its width and height match the declared ratio; invalid mappings are rejected when saved.

Examples

The response uses the same data[0].url shape as OpenAI image generation.

Python · openai

from openai import OpenAI
from pathlib import Path
import requests

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="",
)

result = client.images.generate(
    model="MonaLisa-v1",
    prompt="a quiet glass house beside a lake at dawn",
    size="1024x1024",
    n=1,
)

image = requests.get(result.data[0].url, timeout=60)
image.raise_for_status()
Path("result.webp").write_bytes(image.content)

JavaScript · fetch

const response = await fetch("/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Idempotency-Key": "image-request-001",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "MonaLisa-v1",
    prompt: "a quiet glass house beside a lake at dawn",
    size: "1024x1024",
    n: 1
  })
});

const result = await response.json();
console.log(result.data[0].url);

cURL

curl /models \
  -H "Authorization: Bearer YOUR_API_KEY"

cURL

curl /user/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses and billing

Finished images are copied to this server before the API responds.

200 JSON

{
  "created": 1787980800,
  "data": [
    { "url": "https://your-domain.example/media/outputs/...webp" }
  ]
}

Credits are reserved firstThe request is rejected with 402 when the account cannot cover the full batch.

Failed images are refundedIf a batch only finishes some images, completed images stay charged and the unfinished portion is refunded.

URLs point to saved outputThe temporary upstream URL is downloaded immediately, so callers receive a stable URL from this deployment.

Keep output URLs privateSaved output links act as bearer URLs: anyone with a link can read that image. Do not post them publicly.

Errors

400Invalid model, size, prompt, or count

401Missing or invalid API key

402Not enough credits

409Idempotency key conflict or request still running

501Image editing is not supported

502The upstream generation failed

503Generation is paused

Asynchronous video API

Create a job, poll its status, then download the saved result with the same API key.

Create a video job

POST /v1/videos

Field	Type	Required	Description
`model`	string	Yes	A video model ID returned by GET /v1/models.
`prompt`	string	Yes	Video instructions, up to 8,000 characters.
`seconds`	integer or string	No	One of the durations published by the selected model. Default: 4.
`size`	string	No	An exact resolution published by the model; the first supported size is used by default.
`aspect_ratio`	string	No	Selects a matching published size. The aspectRatio alias is also accepted.
`quality`	string	No	One of the quality IDs published by the model.
`fps`	integer	No	One of the frame rates published by the model, when restricted.

cURL · create

Use one Idempotency-Key per logical video. Repeating the same key and body returns the existing job; changing any video parameter with that key returns HTTP 409.

Poll and download

cURL · status and content

Video object

{
  "id": "video_job_id",
  "object": "video",
  "status": "queued | in_progress | completed | failed | cancelled",
  "progress": 0,
  "model": "",
  "seconds": "4",
  "size": "1280x720",
  "quality": "standard",
  "content_url": "https://your-domain.example/v1/videos/video_job_id/content",
  "error": null
}

Content stays privateThe content URL is owner-scoped and still requires Authorization: Bearer YOUR_API_KEY.

Credits are reserved firstA request without enough credits returns HTTP 402 before the upstream job is created.

Accepted jobs may remain billableThe generic protocol has no portable cancel operation. A timeout, failure, or local cancellation after upstream acceptance can remain charged and may require provider-side review.

Compatibility is intentionally narrow: the configured provider must accept POST /videos and expose GET /videos/{id}. Vendor-specific paths, signatures, callbacks, request fields, or cancellation APIs require a dedicated adapter.