openapi: 3.1.0
info:
  title: ZeroGPU API
  version: "1.0"
  description: |
    REST API for ZeroGPU model inference: `POST /v1/responses` and `POST /v1/chat/completions` (model-dependent).
    Authentication uses `x-api-key` and `x-project-id` headers on every request.
    Documentation: https://docs.zerogpu.ai
servers:
  - url: https://api.zerogpu.ai/v1
    description: Production

security:
  - ApiKey: []
    ProjectId: []

paths:
  /responses:
    post:
      operationId: createResponse
      summary: Send input to a model and receive a response
      tags:
        - Responses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResponseRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
        "400":
          description: Bad request — invalid body
        "401":
          description: Unauthorized — invalid or missing API key
        "403":
          description: Forbidden — invalid project ID or permissions
        "420":
          description: Input exceeds model token limit (context_length_exceeded)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error

  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Chat-completions style inference (OpenAI-compatible shape for some models)
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateChatCompletionRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletionResponse"
        "400":
          description: Bad request — invalid body
        "401":
          description: Unauthorized — invalid or missing API key
        "403":
          description: Forbidden — invalid project ID or permissions
        "420":
          description: Input exceeds model token limit (context_length_exceeded)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error

components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
    ProjectId:
      type: apiKey
      in: header
      name: x-project-id

  schemas:
    CreateResponseRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: Model identifier from the ZeroGPU dashboard (e.g. summarization or IAB classify).
        input:
          description: |
            Model-dependent input. Many production models accept a **plain string**.
            Others accept a **chat-style message list** (`role` + `content`). Use the shape
            required by your model; see [docs](https://docs.zerogpu.ai/api-reference/endpoint/responses).
          oneOf:
            - type: string
              minLength: 1
              description: Plain text prompt or document text.
            - type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/InputMessage"
        text:
          $ref: "#/components/schemas/TextResponseConfig"
        metadata:
          type: object
          additionalProperties: true
          description: |
            Optional model-specific parameters (e.g. PII `mask`, `usecase`). Omit when not required.

    CreateChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: Model identifier from the ZeroGPU dashboard.
        messages:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/ChatMessage"
        metadata:
          type: object
          additionalProperties: true
          description: Optional model-specific parameters (e.g. PII options).

    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: Message role
          enum:
            - system
            - user
            - assistant
        content:
          type: string
          description: Message text

    ChatCompletionResponse:
      type: object
      description: Chat completion payload (shape varies by model; extra fields allowed).
      additionalProperties: true
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
          format: int64
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          $ref: "#/components/schemas/TokenUsage"

    InputMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: Message author role
          enum:
            - user
            - system
        content:
          type: string
          description: Message text

    TextResponseConfig:
      type: object
      properties:
        format:
          type: object
          properties:
            type:
              type: string
              description: Response format type (e.g. `text`)
              example: text

    Response:
      type: object
      required:
        - id
        - object
        - created
        - model
        - output
      properties:
        id:
          type: string
          example: resp_abc123
        object:
          type: string
          example: response
        created:
          type: integer
          format: int64
          description: Unix timestamp when the response was created
        model:
          type: string
        output:
          type: array
          items:
            $ref: "#/components/schemas/OutputMessage"
        usage:
          $ref: "#/components/schemas/TokenUsage"

    OutputMessage:
      type: object
      properties:
        type:
          type: string
          example: message
        role:
          type: string
          example: assistant
        content:
          type: array
          items:
            $ref: "#/components/schemas/OutputContentBlock"

    OutputContentBlock:
      type: object
      properties:
        type:
          type: string
          example: output_text
        text:
          type: string
          description: Generated model output

    TokenUsage:
      type: object
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer

    ErrorResponse:
      type: object
      description: Error payload (e.g. context length exceeded)
      additionalProperties: true