> ## Documentation Index
> Fetch the complete documentation index at: https://impossibl.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate images (OpenAI-compatible)

> OpenAI-compatible image generation with `openai/gpt-image-2`. Returns
base64-encoded image bytes (never URLs). Billed per token — text input
plus image output tokens — from the prepaid balance; there is no BYOK
path for image generation yet.




## OpenAPI

````yaml /openapi.yaml post /v1/images/generations
openapi: 3.1.0
info:
  title: Impossibl AI API
  version: 0.0.1
  description: >
    The Impossibl AI API is one API for all AI providers, OpenAI-compatible
    across OpenAI,

    Anthropic, Google, xAI, and more (`GET /v1/models` lists the full catalog),

    billed from a prepaid credit balance.


    Provider usage is billed at provider list prices with no usage markup.

    Prepaid credit purchases charge a separate fixed 5% platform fee before tax.


    **Agent quickstart**

    1. `POST /v1/accounts` — create a funded account; you get an API key and a
       signup-bonus balance in one call (no human step required).
    2. Call `POST /v1/chat/completions`, `POST /v1/responses`, or
       `POST /v1/audio/transcriptions` with
       `Authorization: Bearer <key>` and a `provider/model` id from `GET /v1/models`.
    3. Credits are deducted per request by token or audio-duration usage; check
    `GET /v1/account`.
servers:
  - url: https://api.impossibl.com
    description: Production
  - url: http://localhost:8787
    description: Local dev
security:
  - BearerKey: []
paths:
  /v1/images/generations:
    post:
      summary: Generate images (OpenAI-compatible)
      description: |
        OpenAI-compatible image generation with `openai/gpt-image-2`. Returns
        base64-encoded image bytes (never URLs). Billed per token — text input
        plus image output tokens — from the prepaid balance; there is no BYOK
        path for image generation yet.
      operationId: createImageGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - prompt
              properties:
                model:
                  type: string
                  enum:
                    - openai/gpt-image-2
                prompt:
                  type: string
                'n':
                  type: integer
                  default: 1
                  description: Number of images to generate.
                size:
                  type: string
                  description: >-
                    `{width}x{height}` (e.g. `1024x1024`, `1536x1024`) or
                    `auto`.
                quality:
                  type: string
                  enum:
                    - auto
                    - low
                    - medium
                    - high
                    - standard
                    - hd
                background:
                  type: string
                  enum:
                    - auto
                    - transparent
                    - opaque
                output_format:
                  type: string
                  enum:
                    - png
                    - jpeg
                    - webp
                output_compression:
                  type: integer
                  minimum: 0
                  maximum: 100
                  description: JPEG/WebP only.
                user:
                  type: string
                  description: >-
                    Stable per-user id forwarded to the provider for abuse
                    monitoring.
      responses:
        '200':
          description: Generated images with token usage.
          content:
            application/json:
              schema:
                type: object
                properties:
                  created:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        b64_json:
                          type: string
                          description: Base64-encoded image bytes.
                        revised_prompt:
                          type: string
                  usage:
                    type: object
                    properties:
                      total_tokens:
                        type: integer
                      input_tokens:
                        type: integer
                      output_tokens:
                        type: integer
                      input_tokens_details:
                        type: object
                        properties:
                          text_tokens:
                            type: integer
                          image_tokens:
                            type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '404':
          $ref: '#/components/responses/UnknownModel'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/ProviderNotConfigured'
components:
  responses:
    BadRequest:
      description: Malformed request (bad JSON, or missing required fields).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: '`model` and `messages` are required'
              type: invalid_request_error
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Invalid API key
              type: authentication_error
    InsufficientCredits:
      description: The account's credit balance is empty. Top up to continue.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Insufficient credits. Top up to continue.
              type: insufficient_quota
    UnknownModel:
      description: The requested `model` id is not in the registry (see GET /v1/models).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: 'Unknown model: foo/bar'
              type: invalid_request_error
    UpstreamError:
      description: The upstream provider returned an error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: 'permission-denied: ...'
              type: upstream_error
    ProviderNotConfigured:
      description: The provider for this model has no API key configured on the gateway.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: 'Provider not configured: missing OPENAI_API_KEY'
              type: provider_not_configured
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              description: >-
                One of authentication_error, invalid_request_error,
                insufficient_quota, upstream_error, provider_not_configured.
  securitySchemes:
    BearerKey:
      type: http
      scheme: bearer
      description: Gateway API key (`imp-rt-...`) from POST /v1/accounts or /v1/keys.

````