Opper AI Images API

openapi: 3.2.0
info:
  description: Schema-driven generative API that orchestrates LLM-powered workflows.
  title: Task Images API
  version: 3.0.0
servers:
- description: Production
  url: https://api.opper.ai
- description: Local development
  url: http://localhost:8080
security:
- BearerAuth: []
tags:
- description: Synchronous image generation
  name: Images
paths:
  /v3/images:
    post:
      description: 'Generate one or more images. By default runs synchronously and returns them inline (200). Set `async: true` to run a single image on the background worker and get a 202 with a status URL to poll instead — use it for slow models (e.g. gpt-image high, imagen ultra) that can exceed the synchronous timeout. `model` and `prompt` are required; `n` (max 4; async is single-image), `size`/`aspect_ratio`, `quality`, and `style` are normalized, and everything in `parameters` is forwarded verbatim to the provider. `image`/`mask`/`reference_images` accept an http(s) URL, a data-URI, or a `file_` for edit / image-to-image. `response_format` defaults to `b64_json`. Set `store: true` to also save the outputs to /v3/files and get a reusable `file_id`; nothing is stored otherwise.'
      operationId: createImage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
          description: Successful response
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageJobResponse'
          description: 'Accepted – async generation submitted (async: true). Poll the returned `status_url` (GET /v3/artifacts/{id}/status) for a presigned download URL when complete.'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          description: Unauthorized - missing or invalid API key
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Generate an image
      tags:
      - Images
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          properties:
            code:
              type: string
            details:
              description: Any value
            message:
              type: string
          required:
          - code
          - message
          type: object
        meta:
          type: object
      required:
      - error
      type: object
    ImageResponse:
      properties:
        created:
          type: integer
        data:
          items:
            properties:
              b64_json:
                type: string
              file_id:
                type: string
              mime_type:
                type: string
              revised_prompt:
                type: string
              url:
                type: string
            type: object
          type: array
        id:
          type: string
        model:
          type: string
        usage:
          properties:
            cost:
              type: number
            images:
              type: integer
          required:
          - cost
          - images
          type: object
      required:
      - id
      - model
      - created
      - data
      - usage
      type: object
    ImageRequest:
      properties:
        aspect_ratio:
          type: string
        async:
          description: Run generation on the background worker and return a job to poll (202) instead of waiting inline (200). Use for slow models. Single-image only.
          type: boolean
        image:
          type: string
        mask:
          type: string
        model:
          type: string
        n:
          type: integer
        parameters:
          type: object
        prompt:
          type: string
        quality:
          type: string
        reference_images:
          items:
            type: string
          type: array
        resolution:
          description: Output-resolution tier for models that declare one (e.g. xAI 1k/2k). Separate axis from quality.
          type: string
        response_format:
          type: string
        size:
          type: string
        store:
          description: Persist each generated image to /v3/files and return a reusable file_id per image. Defaults to false; set true to store.
          type: boolean
      required:
      - model
      - prompt
      type: object
    ImageJobResponse:
      properties:
        id:
          type: string
        status_url:
          type: string
      required:
      - id
      - status_url
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API Key
      description: API key authentication. Pass your API key as a Bearer token.
      scheme: bearer
      type: http
    MCPBearer:
      description: Delegated user OAuth access token for the Opper MCP resource. Obtain through advertised OAuth authorization; runtime and management service keys are not accepted.
      scheme: bearer
      type: http
    ManagementBearer:
      bearerFormat: Management API Key
      description: Management API authentication. Pass an `op-mak-…` management token as a Bearer token. Runtime `op-…` API keys are rejected with 403 — they belong on the data-plane endpoints. Mint a management key from the platform UI under Settings → API keys.
      scheme: bearer
      type: http