---
title: "Image Generation"
method: POST
path: "/v1/images/generate"
tags: ["Suprsonic"]
---

# Image Generation

`POST /v1/images/generate`

## Request

- Base URL: `https://suprsonic.ai`
- URL: `https://suprsonic.ai/v1/images/generate`
- Auth: HTTP bearer

Generate images from text prompts. Returns a hosted URL of the image and the same image as base64 (b64_json), with its content_type (image/png or image/jpeg, as the bytes are), the aspect ratio and the size used. Use to create a new picture from a description. To cut the background out of an existing image use bg-remove; to capture a web page use screenshot. Cost: 512px 1 credit, 1K 2 credits, 2K 3 credits, 4K 5 credits, charged only when a call succeeds.

## Request body

- ImageGenerateRequest
  - `prompt` string, required: Describe a CONCRETE, grounded scene: real people, real objects, physical screens and devices, natural light, editorial photography quality (or a clean minimal illustration of the actual concept). Words like 'futuristic', 'holographic', 'glowing', or neon-tech scenery produce the same generic AI-cliche image every time; describe the present-day, physical version of the scene instead.
  - `aspect_ratio` string
  - `image_size` string
  - `reference_image_url` string, nullable
  - `skip_default_style` boolean: Leave false (recommended). False applies the house visual style guidance (grounded realistic imagery, avoids overused AI-tech cliches). Set true ONLY when you are deliberately providing complete art direction of your own and want zero house styling.

## Response `200`

The call's envelope: success, data (the capability's result), metadata, and credits_used (0 when the call did not succeed).

- UnifiedResponse: Standard envelope for all unified API responses.
  - `success` boolean, required
  - `data` union
    - object
    - unknown[]
      - unknown
  - `error` UnifiedError: RFC 7807 problem detail for machine-actionable errors.
    - `type` string, required
    - `title` string, required
    - `status` integer, required
    - `detail` string, nullable
    - `is_retriable` boolean
    - `retry_after_seconds` integer, nullable
    - `alternative_action` string, nullable
    - `error_category` string
    - `caller_error` string, nullable
  - `metadata` UnifiedMetadata: Metadata included in every unified API response.
    - `provider_used` string, nullable
    - `providers_tried` string[]
    - `mode_used` string, nullable
    - `response_time_ms` integer
    - `request_id` string
    - `capability` string, nullable
    - `params` object, nullable
  - `credits_used` integer

## Other responses

- `401`: No API key, or one that was not found or is revoked.
- `402`: Not enough credits for this call. The error's alternative_action says where to add them.
- `403`: The account is restricted by a billing issue.
- `422`: Validation Error
- `429`: The key's rate limit is reached. The error's retry_after_seconds says when to try again.

---

[API](https://skmtc.dev/o-mega/apis/suprsonic-api.md) - [All operations](https://skmtc.dev/o-mega/apis/suprsonic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/o-mega/apis/suprsonic-api/revisions/0eb535eb5679?raw)