openapi: 3.1.0
info:
  title: Image Router API
  version: 0.0.1
servers:
  - url: https://api.imagerouter.io
components:
  schemas:
    ImageGenerationRequest:
      type: object
      properties:
        prompt:
          type: string
          maxLength: 20000
        model:
          type: string
          minLength: 1
        response_format:
          type: string
          enum: &a1
            - url
            - b64_json
            - b64_ephemeral
          default: url
        quality:
          type: string
          enum: &a2
            - auto
            - low
            - medium
            - high
          default: auto
        size:
          type: string
          default: auto
        output_format:
          type: string
      required:
        - model
    VideoGenerationRequest:
      type: object
      properties:
        prompt:
          type: string
          maxLength: 20000
        model:
          type: string
          minLength: 1
        response_format:
          type: string
          enum: &a3
            - url
            - b64_json
            - b64_ephemeral
          default: url
        quality:
          type: string
          enum: &a4
            - auto
            - low
            - medium
            - high
          default: auto
        size:
          type: string
          default: auto
        seconds:
          anyOf:
            - type: string
              enum:
                - auto
            - type: number
              minimum: 1
              maximum: 60
          default: auto
      required:
        - model
    ChatCompletionRequest:
      type: object
      properties:
        model:
          type: string
          minLength: 1
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
              content: {}
            required:
              - role
          minItems: 1
      required:
        - model
        - messages
    ResponsesRequest:
      type: object
      properties:
        model:
          type: string
          minLength: 1
        input:
          anyOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  role:
                    type: string
                  content: {}
      required:
        - model
        - input
    ImageGenerationWithUploads:
      type: object
      properties:
        prompt:
          type: string
          maxLength: 20000
        model:
          type: string
          minLength: 1
        response_format:
          type: string
          enum: *a1
          default: url
        quality:
          type: string
          enum: *a2
          default: auto
        size:
          type: string
          default: auto
        output_format:
          type: string
        image:
          type: string
          format: binary
        image[]:
          type: string
          format: binary
        mask:
          type: string
          format: binary
        mask[]:
          type: string
          format: binary
      required:
        - model
    VideoGenerationWithImageRequest:
      type: object
      properties:
        prompt:
          type: string
          maxLength: 20000
        model:
          type: string
          minLength: 1
        response_format:
          type: string
          enum: *a3
          default: url
        quality:
          type: string
          enum: *a4
          default: auto
        size:
          type: string
          default: auto
        seconds:
          anyOf:
            - type: string
              enum:
                - auto
            - type: number
              minimum: 1
              maximum: 60
          default: auto
        image:
          type: string
          format: binary
        image[]:
          type: string
          format: binary
      required:
        - model
  parameters: {}
paths:
  /v1/openai/images/generations:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  maxLength: 20000
                model:
                  type: string
                  minLength: 1
                response_format:
                  type: string
                  enum: *a1
                  default: url
                quality:
                  type: string
                  enum: *a2
                  default: auto
                size:
                  type: string
                  default: auto
                output_format:
                  type: string
              required:
                - model
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/ImageGenerationWithUploads"
      responses:
        "200":
          description: Success
  /v1/openai/videos/generations:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  maxLength: 20000
                model:
                  type: string
                  minLength: 1
                response_format:
                  type: string
                  enum: *a3
                  default: url
                quality:
                  type: string
                  enum: *a4
                  default: auto
                size:
                  type: string
                  default: auto
                seconds:
                  anyOf:
                    - type: string
                      enum:
                        - auto
                    - type: number
                      minimum: 1
                      maximum: 60
                  default: auto
              required:
                - model
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/VideoGenerationWithImageRequest"
      responses:
        "200":
          description: Success
  /v1/openai/images/edits:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  maxLength: 20000
                model:
                  type: string
                  minLength: 1
                response_format:
                  type: string
                  enum: *a1
                  default: url
                quality:
                  type: string
                  enum: *a2
                  default: auto
                size:
                  type: string
                  default: auto
                output_format:
                  type: string
              required:
                - model
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/ImageGenerationWithUploads"
      responses:
        "200":
          description: Success
  /v1/openai/chat/completions:
    post:
      description: "OpenAI-compatible Chat Completions endpoint for text (LLM) models.
        Requests are proxied to LLMGateway and billed on the true cost. Supports
        streaming (set `stream: true`)."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  minLength: 1
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                      content: {}
                    required:
                      - role
                  minItems: 1
              required:
                - model
                - messages
      responses:
        "200":
          description: Success (JSON, or text/event-stream when stream=true)
          content:
            application/json:
              schema:
                type: object
                properties: {}
                description: Chat completion response (when stream=false)
            text/event-stream:
              schema:
                type: string
                description: Server-sent events stream of chat completion chunks (when
                  stream=true)
  /v1/openai/responses:
    post:
      description: "OpenAI-compatible Responses endpoint for text (LLM) models.
        Requests are proxied to LLMGateway and billed on the true cost. Supports
        streaming (set `stream: true`)."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  minLength: 1
                input:
                  anyOf:
                    - type: string
                    - type: array
                      items:
                        type: object
                        properties:
                          role:
                            type: string
                          content: {}
              required:
                - model
                - input
      responses:
        "200":
          description: Success (JSON, or text/event-stream when stream=true)
          content:
            application/json:
              schema:
                type: object
                properties: {}
                description: Response object (when stream=false)
            text/event-stream:
              schema:
                type: string
                description: Server-sent events stream of response chunks (when stream=true)
  /v1/models:
    get:
      responses:
        "200":
          description: Success
  /v1/auth/test:
    post:
      responses:
        "200":
          description: API key valid
        "401":
          description: Unauthorized
  /v1/api-keys:
    post:
      description: Create a new normal API key for the account that owns the supplied
        **management** API key. The Authorization header must contain a
        management key (Bearer). Management keys cannot be used to call any
        other endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Human-readable name for the new API key
                spend_limit:
                  type:
                    - number
                    - "null"
                  description: Optional spend cap in USD. Requests are blocked once the key has
                    spent this amount within the current window (see
                    `spend_limit_period`). Omit or set to null for no limit. The
                    owner can change it later from the API keys dashboard.
                  example: 5
                spend_limit_period:
                  type:
                    - string
                    - "null"
                  enum:
                    - day
                    - week
                    - month
                  description: Optional reset window for `spend_limit`. `day`/`week`/`month` reset
                    at 00:00 UTC on the corresponding boundary (today / Monday /
                    1st of the month). Omit or set to null for a
                    lifetime/cumulative cap. Requires `spend_limit` to be set.
                  example: month
                expires_at:
                  type:
                    - string
                    - "null"
                  description: Optional ISO 8601 timestamp at which the key automatically stops
                    working. Must be in the future. Omit or set to null to never
                    expire.
                  example: 2027-01-01T00:00:00Z
              required:
                - name
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  key:
                    type: string
                    description: The generated API key. Shown only once.
                  created_at:
                    type: string
                  is_active:
                    type: boolean
                  is_management:
                    type: boolean
                  spend_limit:
                    type:
                      - number
                      - "null"
                    description: Spend cap in USD, or null when no limit is set.
                  spend_limit_period:
                    type:
                      - string
                      - "null"
                    enum:
                      - day
                      - week
                      - month
                    description: Reset window for the spend limit, or null for lifetime cap.
                  expires_at:
                    type:
                      - string
                      - "null"
                    description: Expiration timestamp, or null when the key never expires.
                required:
                  - id
                  - name
                  - key
                  - created_at
                  - is_active
                  - is_management
                  - spend_limit
                  - spend_limit_period
                  - expires_at
        "400":
          description: Invalid request body
        "401":
          description: Unauthorized — management key required
  /v1/credits:
    get:
      parameters:
        - schema:
            type: string
            description: If true, returns usage broken down by API key
          required: false
          name: by_api_key
          in: query
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  remaining_credits:
                    type: string
                  credit_usage:
                    type: string
                  total_deposits:
                    type: string
                  usage_by_api_key:
                    type: array
                    items:
                      type: object
                      properties:
                        api_key_id:
                          type: string
                        api_key_name:
                          type: string
                        credit_usage:
                          type: string
                        total_requests:
                          type: number
                        created_at:
                          type:
                            - string
                            - "null"
                        is_active:
                          type: boolean
                        spend_limit:
                          type:
                            - string
                            - "null"
                        spend_limit_period:
                          type:
                            - string
                            - "null"
                          enum:
                            - day
                            - week
                            - month
                        period_spend:
                          type: string
                        period_start:
                          type:
                            - string
                            - "null"
                        expires_at:
                          type:
                            - string
                            - "null"
                      required:
                        - api_key_id
                        - api_key_name
                        - credit_usage
                        - total_requests
                        - created_at
                        - is_active
                        - spend_limit
                        - spend_limit_period
                        - period_spend
                        - period_start
                        - expires_at
                required:
                  - remaining_credits
                  - credit_usage
                  - total_deposits
webhooks: {}