Image generation

Status: Preview. The endpoints are callable and may still evolve before GA.

Use image generation for product imagery, thumbnails, creative iteration, and follow-up edits driven by reference images.

Billing

Image generation is prepaid and per image. The wallet is debited for n × single_price at task creation; if the model returns fewer images than requested, the difference is refunded automatically. Failed tasks refund in full.

Capability	Quality	Price	USD reference (default `1000 cr/$`)
`text_to_image`	`standard`	`50.0000` credits / image	`≈ $0.0500`
`text_to_image`	`hd`	`300.0000` credits / image	`≈ $0.3000`
`image_to_image`	`standard`	`60.0000` credits / image	`≈ $0.0600`
`image_to_image`	`hd`	`320.0000` credits / image	`≈ $0.3200`

The task envelope exposes the live charge under billing.charged_credits and any partial refund under billing.refunded_credits once the task finalizes.

Endpoints

Endpoint	Use it for
`POST /v1/images/generations`	Generate images from a prompt.
`POST /v1/images/image-to-image`	Generate images from one or more reference images plus a prompt.
`GET /v1/tasks/{task_id}`	Poll the async task until it succeeds, fails, or is canceled.
`POST /v1/uploads`	Upload a reference image first when you want to reuse it by `artifact_id`.

Text to image

POST /v1/images/generations
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: <uuid>

{
  "model": "auto",
  "prompt": "a tiny enamel pin of a sleeping cat",
  "quality": "standard",
  "aspect_ratio": "1:1",
  "n": 1
}

The response is 202 Accepted with a task_id.

model accepts "auto" (routes to the best available model) or a concrete id ("gpt-image-2" today). quality is "standard" or "hd". aspect_ratio is one of "auto", "1:1", "16:9", "9:16", "4:3", "3:4", "2:1". n is 1–4. aspect_ratio="auto" only runs at standard quality.

Image to image

Feed up to 16 reference images and a prompt:

{
  "model": "auto",
  "prompt": "watercolor variant of this scene",
  "image": {
    "type": "artifact",
    "artifact_id": "artifact_01J..."
  },
  "quality": "standard",
  "aspect_ratio": "1:1",
  "n": 1
}

image is required; extra_images[] adds up to 15 more, all of the same media types accepted by image (url, artifact, data_uri). External HTTPS URLs and base64 data URIs are ingested into your tenant storage before the model runs so the returned artifact_ids are reusable.

Chaining

Every result item carries an artifact_id you can feed back into a follow-up image_to_image call without re-uploading:

{
  "type": "image_to_image",
  "model": "gpt-image-2",
  "images": [
    {
      "url": "https://cdn.beatra.../artifact_01J....png",
      "artifact_id": "artifact_01J....",
      "format": "png",
      "mime_type": "image/png",
      "size_bytes": 2015524
    }
  ]
}

Delivery

Image tasks follow the async task model. Poll GET /v1/tasks/{task_id} and read the URL + artifact_id from each output.images[] entry once the task is succeeded.