openapi: 3.1.0
info:
  title: imageat API
  version: 1.1.0
  description: OpenAI-compatible text and agent APIs plus image and video generation.
servers:
  - url: https://imageat.com/api/v1
security:
  - bearerAuth: []
paths:
  /models:
    get:
      operationId: listModels
      responses:
        '200': { description: Model list }
  /models/images:
    get:
      operationId: listImageModels
      responses:
        '200': { description: Image model list }
  /models/videos:
    get:
      operationId: listVideoModels
      responses:
        '200': { description: Video model list }
  /chat/completions:
    post:
      operationId: createChatCompletion
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChatRequest' }
      responses:
        '200': { description: Chat completion or SSE stream }
        '429': { $ref: '#/components/responses/RateLimited' }
  /responses:
    post:
      operationId: createResponse
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ResponseRequest' }
      responses:
        '200': { description: Response object or typed SSE stream }
  /responses/{response_id}:
    parameters:
      - name: response_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveResponse
      responses:
        '200': { description: Stored response }
    delete:
      operationId: deleteResponse
      responses:
        '200': { description: Deleted response marker }
  /responses/{response_id}/cancel:
    post:
      operationId: cancelResponse
      parameters:
        - name: response_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Cancelled response }
  /images:
    post:
      operationId: createImage
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200': { description: Generated image URLs }
  /videos:
    post:
      operationId: createVideo
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200': { description: Completed video or asynchronous task }
  /videos/status:
    get:
      operationId: getVideoStatus
      parameters:
        - { name: taskId, in: query, required: true, schema: { type: string } }
        - { name: generationId, in: query, required: false, schema: { type: string } }
      responses:
        '200': { description: Video task status }
  /videos/cancel:
    post:
      operationId: cancelVideo
      responses:
        '200': { description: Cancelled and refunded video task }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string, maxLength: 255 }
  responses:
    RateLimited:
      description: Rate limit exceeded; retry after the number of seconds in Retry-After.
  schemas:
    ChatRequest:
      type: object
      required: [model, messages]
      properties:
        model: { type: string }
        messages: { type: array, items: { type: object, additionalProperties: true } }
        tools: { type: array, items: { type: object, additionalProperties: true } }
        tool_choice: { oneOf: [{ type: string }, { type: object }] }
        parallel_tool_calls: { type: boolean, default: true }
        reasoning: { type: string, enum: [low, medium, high, xhigh, max] }
        verbosity: { type: string, enum: [low, medium, high] }
        web_search: { type: boolean, default: false }
        max_tokens: { type: integer, minimum: 1, maximum: 4000, default: 1000 }
        stream: { type: boolean, default: false }
    ResponseRequest:
      type: object
      required: [model, input]
      properties:
        model: { type: string }
        input: { oneOf: [{ type: string }, { type: array, items: { type: object, additionalProperties: true } }] }
        instructions: { type: string }
        previous_response_id: { type: string }
        tools: { type: array, items: { type: object, additionalProperties: true } }
        parallel_tool_calls: { type: boolean, default: true }
        reasoning: { oneOf: [{ type: string }, { type: object, additionalProperties: true }] }
        verbosity: { type: string, enum: [low, medium, high] }
        web_search: { type: boolean, default: false }
        stream: { type: boolean, default: false }
        store: { type: boolean, default: true }