kymaapi-com Images API

openapi: 3.2.0
info:
  title: Kymaapi Com Images API
  version: 1.0.0
  contact:
    name: Kyma API
    url: https://kymaapi.com
    email: support@kymaapi.com
  license:
    name: Proprietary
  termsOfService: https://kymaapi.com/terms
  description: 'Operations tagged Images across 2 of this provider''s published API definitions: kymaapi-com-openapi.json, kymaapi-com-v1-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://kymaapi.com/v1
  description: Production
security:
- BearerAuth: []
tags:
- name: Images
paths:
  /images/generations:
    post:
      operationId: createImageGeneration
      summary: Create image generation (async)
      description: 'Generate or edit images. Asynchronous — returns 202 with a job_id immediately; poll GET /v1/jobs/{id} for the result. Models: see GET /v1/models for the live image catalogue. Billed per image; failures are refunded in full.'
      tags:
      - Images
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              - prompt
              properties:
                model:
                  type: string
                  description: 'Image model ID. Pick by task: gpt-image-2 = best text-in-image (multilingual, logos, posters); gpt-image-2.5-flare = consistent characters from reference images, exact text-in-image; flux-2-pro = photoreal + multi-reference blend (up to 10 source images); recraft-v4-pro = print-ready 4MP design; recraft-v4-vector = native SVG output with editable paths; ideogram-v3 = typography specialist; recraft-v4 = #1 HF Arena daily default; flux-kontext-pro = image edit/inpaint (REQUIRES image_url); minimax-image-01 = sub-cent budget tier.'
                  enum:
                  - gpt-image-2
                  - gpt-image-2.5-flare
                  - flux-2-pro
                  - recraft-v4
                  - recraft-v4-pro
                  - recraft-v4-vector
                  - ideogram-v3
                  - flux-kontext-pro
                  - minimax-image-01
                prompt:
                  type: string
                  maxLength: 4000
                  description: Natural-language description of the image. For text-in-image with gpt-image-2, quote the literal text you want rendered (e.g., 'a poster reading "Open Late Friday" in bold serif'). Server normalizes to NFC before length check so stacked-diacritic scripts (Vietnamese, Hindi, Arabic) measure correctly.
                n:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                  description: Number of images to generate. Billed per output image. gpt-image-2 supports up to 10; other models cap at 4. A request with n=4 books and bills 4× the per-image price.
                size:
                  type: string
                  description: Output dimensions as WIDTHxHEIGHT (e.g., 1024x1024, 1024x1536, 1536x1024, 2048x2048) or 'auto'. gpt-image-2 supports 1024x1024 / 1024x1536 / 1536x1024 / 2048x2048; values outside that enum snap to 1024x1024. gpt-image-2.5-flare supports 1024x1024 / 1024x1536 / 1536x1024 / auto; a side above 1536 returns 400 invalid_parameter. Recraft V4 and FLUX.2 Pro accept fal-style aspect enums (square_hd, landscape_16_9, portrait_4_3, etc.) which the gateway maps for you. For per-MP pricing models (flux-2-pro), bigger sizes cost more.
                quality:
                  type: string
                  enum:
                  - low
                  - medium
                  - high
                  - auto
                  default: medium
                  description: 'Consumed by gpt-image-2 and gpt-image-2.5-flare (ignored elsewhere). Sets the OpenAI quality tier and the per-image price: gpt-image-2 low=$0.009, medium=$0.072, high=$0.285; gpt-image-2.5-flare low=$0.009, medium=$0.019, high=$0.285, plus $0.012 per reference image (image_url / image_urls) once per request. The hold books the full amount up front. ''auto'' or omitted bills medium.'
                image_url:
                  type: string
                  description: HTTPS URL of a source image. REQUIRED for flux-kontext-pro (image edit). Optional for gpt-image-2 and gpt-image-2.5-flare, which edit from it as a reference (on gpt-image-2.5-flare each reference image adds $0.012).
                image_urls:
                  type: array
                  items:
                    type: string
                  maxItems: 16
                  description: Multi-reference input. gpt-image-2 and gpt-image-2.5-flare accept up to 16 HTTPS URLs (gpt-image-2.5-flare adds $0.012 per reference, once per request); flux-2-pro accepts up to 10 and blends them; other models up to 10. More than the model's cap returns 400 too_many_references. When both image_url and image_urls are present, image_urls wins.
                idempotency_key:
                  type: string
                  maxLength: 128
                  description: Deduplication key. Resending the same request body with the same key within the retention window returns the existing job (200 OK with the original ImageJob), not a new charge. Safe to retry 5xx responses.
                extra:
                  type: object
                  description: Pass-through to the underlying model. Validated upstream — invalid keys return 400 from the provider, not 500.
      responses:
        '200':
          description: Idempotent replay — same idempotency_key returns the existing job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageJob'
        '202':
          description: Job accepted; poll GET /v1/jobs/{id} for status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://kymaapi.com/v1
      description: Production
  /jobs/{id}:
    get:
      operationId: getJob
      summary: Get job status
      description: Fetch the current state of an async job (image generation, etc.). Same response shape as POST /v1/images/generations.
      tags:
      - Images
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Job not found or not owned by this API key
    servers:
    - url: https://kymaapi.com/v1
      description: Production
components:
  schemas:
    PaymentRequired:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              enum:
              - billing_error
              description: Always `billing_error`, on every surface.
            code:
              type: string
              enum:
              - model_requires_paid
              - insufficient_credits
              description: The rule that refused.
            param:
              type: string
              nullable: true
            retryable:
              type: boolean
            request_id:
              type: string
            doc_url:
              type: string
        type:
          type: string
          enum:
          - error
          description: Anthropic-compat envelope marker. Only on /v1/messages.
        topup:
          type: string
          description: Machine top-up endpoint. An agent with a wallet and no human can pay here; it is a hint in the body, never a payment challenge.
          example: https://api.kymaapi.com/v1/topup
        need_usd:
          type: number
          description: Worst-case cost of this request, USD. `insufficient_credits` only.
        have_usd:
          type: number
          description: Spendable credit at the moment of the refusal, USD. `insufficient_credits` only.
        balance:
          type: number
          description: Mirror of `details.balance`.
        required:
          type: number
          description: 'Mirror of `details.required`. Zero on `model_requires_paid`: no top-up amount makes a premium model callable on signup credit.'
        topup_url:
          type: string
          description: Billing page for a human. Mirror of `details.topup_url`.
          example: https://kymaapi.com/billing
        details:
          type: object
          properties:
            balance:
              type: number
            required:
              type: number
            topup_url:
              type: string
            hint:
              type: string
            endpoint_id:
              type: string
              description: The model the caller asked for.
          description: The nested envelope the media, audio and Anthropic-compat surfaces emit. Read this first; the top-level mirrors exist for older parsers. (/v1/embeddings emits the same envelope for a low balance, but it has its own check rather than this gate, so it carries neither code.)
      description: 402 — the access gate refused. `model_requires_paid` (signup credit is a free tier, not the whole catalogue) or `insufficient_credits` (the balance does not cover the request).
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: 'One sentence: what happened and what to do next.'
            type:
              type: string
              enum:
              - invalid_request_error
              - authentication_error
              - billing_error
              - permission_error
              - not_found_error
              - request_too_large
              - rate_limit_error
              - timeout_error
              - upstream_error
              - api_error
              description: The category. On /v1/messages, Anthropic's error type for the same condition.
            code:
              type: string
              enum:
              - missing_api_key
              - invalid_api_key
              - invalid_login
              - password_reset_required
              - invalid_google_token
              - permission_denied
              - voice_not_owned
              - session_required
              - csrf_failed
              - route_refused
              - content_refused
              - invalid_json
              - missing_parameter
              - invalid_parameter
              - wrong_endpoint
              - unsupported_content
              - unsupported_media_type
              - request_rejected
              - no_speech_detected
              - segments_unsupported
              - method_not_allowed
              - captcha_failed
              - invalid_signature
              - account_exists
              - request_too_large
              - request_exceeds_tier_limit
              - endpoint_not_found
              - endpoint_retired
              - model_not_found
              - model_retired
              - job_not_found
              - model_requires_paid
              - insufficient_credits
              - tier_required
              - payment_required
              - rate_limit_exceeded
              - concurrency_limit_exceeded
              - media_rate_exceeded
              - queue_full
              - too_many_sessions
              - too_many_attempts
              - signup_paused
              - upstream_rate_limited
              - provider_unavailable
              - model_unavailable
              - upstream_invalid_response
              - upstream_timeout
              - stream_interrupted
              - upload_timeout
              - media_paused
              - service_unavailable
              - internal_error
              - signup_failed
              - settle_failed
              description: 'Stable machine code: added, never renamed or removed. Each has an entry at https://docs.kymaapi.com/api-reference/errors'
            param:
              type: string
              nullable: true
              description: The request field at fault, or null.
            retryable:
              type: boolean
              description: Whether the same request can succeed if sent again (after `Retry-After`). Also sent as the `x-should-retry` header.
            request_id:
              type: string
              description: Same value as the `x-request-id` header. Quote it to support.
              example: req_7f3c2a9e0b1d4c6f8a2e5b7d9c1f3a5e
            doc_url:
              type: string
              description: This code's entry on the errors page.
              example: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
          required:
          - message
          - type
          - code
      required:
      - error
      description: 'Every error body. On /v1/messages the same object sits in Anthropic''s envelope: `type: "error"` on top, an Anthropic `error.type`, and `request_id` also at the top level.'
    ImageJob:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - image.job
        status:
          type: string
          enum:
          - pending
          - processing
          - succeeded
          - failed
          - refunded
          - expired
        model:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          nullable: true
          format: date-time
        output:
          type: object
          nullable: true
          properties:
            url:
              type: string
              description: Vercel Blob URL of the generated image
            metadata:
              type: object
              properties: {}
        error:
          type: object
          nullable: true
          properties:
            message:
              type: string
            code:
              type: string
        estimated_cost:
          type: number
          nullable: true
          description: Hold amount placed at submit time (USD), as the ledger holds it. `null` while the job is queued and nothing is held yet.
        charged_amount:
          type: number
          nullable: true
          description: 'Final billed amount (USD) once the hold is released: what a successful job cost, `0` for a failed or refunded one. `null` until then.'
        refunded_amount:
          type: number
          nullable: true
          description: The part of the hold returned to your balance (USD) once it is released. `null` until then.
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds until the rate limit resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: 'Payment required. One gate decides every refusal and `error.code` names the rule that fired: `model_requires_paid` (the account has never deposited and this model is outside the free tier, which `free_tier` on `GET /v1/models` states in advance) or `insufficient_credits` (the balance does not cover the request; `need_usd` and `have_usd` say by how much). `error.type` is `billing_error` on every surface, /v1/messages included. `topup` is the machine endpoint an agent can pay without a human; `topup_url` is the page for a human.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequired'
          examples:
            model_requires_paid:
              summary: Never funded, premium model — /chat/completions, /completions
              value:
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: This model requires a funded balance. Signup credit covers lower-cost models. Top up at https://kymaapi.com/billing
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: claude-fable-5.1
            insufficient_credits:
              summary: Balance below the worst case — /chat/completions, /completions
              value:
                need_usd: 0.012562
                have_usd: 0.0004
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.0004
                required: 0.012562
                topup_url: https://kymaapi.com/billing
                error:
                  message: This request needs about $0.01 of credit; you have $0.0004. Top up at https://kymaapi.com/billing or lower max_tokens.
                  type: billing_error
                  code: insufficient_credits
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
                details:
                  balance: 0.0004
                  required: 0.012562
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at least $0.02 to run this model — a human can top up at https://kymaapi.com/billing, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: deepseek-v3
            model_requires_paid_messages:
              summary: Never funded, premium model — /messages (Anthropic-compat envelope)
              value:
                type: error
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: This model requires a funded balance. Signup credit covers lower-cost models. Top up at https://kymaapi.com/billing
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: claude-fable-5.1
            model_requires_paid_media:
              summary: Never funded, premium SKU — media and audio surfaces (D3 envelope)
              value:
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: 'gpt-image-2 is not in the free tier; add credits to use it. Free-tier media: gemini-3.5-transcribe, gpt-4o-mini-transcribe-2025-12-15, gpt-transcribe, minimax-image-01, whisper-v3-turbo.'
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: gpt-image-2
            insufficient_credits_media:
              summary: Balance below the job estimate — media and audio surfaces (D3 envelope)
              value:
                need_usd: 0.054
                have_usd: 0.01
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.01
                required: 0.054
                topup_url: https://kymaapi.com/billing
                error:
                  message: This request needs about $0.05 of credit; you have $0.01. Top up at https://kymaapi.com/billing.
                  type: billing_error
                  code: insufficient_credits
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
                details:
                  balance: 0.01
                  required: 0.054
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at least $0.06 to run this model — a human can top up at https://kymaapi.com/billing, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: gpt-image-2
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Kyma API key (starts with ky-) or session token (starts with ks-)
x-refined-from:
- kymaapi-com-openapi.json
- kymaapi-com-v1-openapi.json