openapi: 3.0.0
info:
  title: Orbifold AI Platform
  version: 1.0.0
  description: |
    Centralized API Gateway documentation for Orbifold AI.
    This specification aggregates individual microservice definitions.
  license:
    name: Proprietary
    url: https://orbifold.ai
servers:
  - url: https://api.orbifold.ai
    description: Production Gateway
paths:
  /edit-image:
    post:
      operationId: editImage
      summary: Edit an image using a text prompt
      description: Sends text and images to for processing/editing.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  type: string
                  description: The prompt text
                  example: Describe this image
                images:
                  type: array
                  description: List of images to process
                  items:
                    oneOf:
                      - type: string
                        description: Base64 encoded image string
                      - type: object
                        properties:
                          data:
                            type: string
                            description: Base64 encoded image data
                          base64:
                            type: string
                            description: Alternative key for base64 data
                          mimeType:
                            type: string
                            description: MIME type of the image (e.g. image/jpeg)
                image_mimeType:
                  type: string
                  description: Default MIME type for images if not specified per image
                  default: application/octet-stream
                response_modalities:
                  type: array
                  description: Desired response modalities
                  items:
                    type: string
                  default:
                    - TEXT
                temperature:
                  type: number
                  description: Controls the randomness of the output
                top_p:
                  type: number
                  description: Nucleus sampling parameter
                top_k:
                  type: integer
                  description: Top-k sampling parameter
                max_output_tokens:
                  type: integer
                  description: Maximum number of tokens to generate
                system_instruction:
                  type: string
                  description: System instructions for the model
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  base64_images:
                    type: array
                    items:
                      type: object
                      properties:
                        mime_type:
                          type: string
                        data:
                          type: string
        '400':
          description: Bad Request - Invalid JSON or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway - Upstream model error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string
          example: Error message description
