openapi: 3.1.0
info:
  # Do not change the title, if the title changes, the import paths will be broken
  title: Api
  version: 0.1.0
  description: API specification
servers:
  - url: /api
    description: Base API path
tags:
  - name: health
    description: Health operations
  - name: images
    description: Image generation operations
  - name: config
    description: Configuration operations
paths:
  /healthz:
    get:
      operationId: healthCheck
      tags: [health]
      summary: Health check
      description: Returns server health status
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
  /config/token:
    get:
      operationId: getConfigToken
      tags: [config]
      summary: Get API token status
      description: Check if a Bearer token is configured
      responses:
        "200":
          description: Token status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenStatusResponse"
    post:
      operationId: setConfigToken
      tags: [config]
      summary: Set API token
      description: Save the Bearer token for geminigen.ai API
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetTokenBody"
      responses:
        "200":
          description: Token saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
    delete:
      operationId: deleteConfigToken
      tags: [config]
      summary: Delete API token
      description: Remove the stored Bearer token
      responses:
        "200":
          description: Token removed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
  /images/generate:
    post:
      operationId: generateImage
      tags: [images]
      summary: Generate image
      description: Generate an image using AI based on a text prompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateImageBody"
      responses:
        "200":
          description: Image generated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateImageResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /images/history:
    get:
      operationId: getImageHistory
      tags: [images]
      summary: Get image history
      description: Retrieve the list of previously generated images
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: List of generated images
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageHistoryResponse"
  /images/{id}:
    delete:
      operationId: deleteImage
      tags: [images]
      summary: Delete image
      description: Delete a generated image from history
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Image deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "404":
          description: Image not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  schemas:
    TokenStatusResponse:
      type: object
      properties:
        configured:
          type: boolean
        token:
          type: string
          nullable: true
      required:
        - configured
    SetTokenBody:
      type: object
      properties:
        token:
          type: string
      required:
        - token
    HealthStatus:
      type: object
      properties:
        status:
          type: string
      required:
        - status
    GenerateImageBody:
      type: object
      properties:
        prompt:
          type: string
          description: Text description for image generation
        style:
          type: string
          description: Style of image to generate
          enum: [none, realistic, anime, artistic, cartoon, sketch, oil_painting, watercolor, digital_art]
          default: realistic
        aspectRatio:
          type: string
          description: Aspect ratio for the image
          enum: ["1:1", "16:9", "9:16", "4:3", "3:4", "2:3", "3:2"]
          default: "1:1"
        model:
          type: string
          description: AI model to use
          enum: [grok, meta, imagen-pro, imagen-4, imagen-flash, nano-banana-pro, nano-banana-2]
          default: grok
        resolution:
          type: string
          description: Output resolution for supported models (Nano Banana Pro / Nano Banana 2)
          enum: ["1K", "2K", "4K"]
        referenceImageBase64:
          type: string
          description: Base64-encoded reference image for image-to-image generation (optional)
        referenceImageMime:
          type: string
          description: MIME type of the reference image (e.g. image/jpeg)
        isPrivate:
          type: boolean
          description: Whether this image should be private (only visible to the creator)
          default: false
      required:
        - prompt
    ApiDebugInfo:
      type: object
      properties:
        requestUrl:
          type: string
        requestMethod:
          type: string
        requestHeaders:
          type: object
          additionalProperties:
            type: string
        requestBody:
          type: object
        responseStatus:
          type: integer
        responseBody:
          type: object
        durationMs:
          type: number
        usedFallback:
          type: boolean
        fallbackReason:
          type: string
      required:
        - requestUrl
        - requestMethod
        - requestHeaders
        - requestBody
        - responseStatus
        - responseBody
        - durationMs
        - usedFallback
    GenerateImageResponse:
      type: object
      properties:
        id:
          type: integer
        imageUrl:
          type: string
        prompt:
          type: string
        style:
          type: string
        aspectRatio:
          type: string
        model:
          type: string
        createdAt:
          type: string
          format: date-time
        apiDebug:
          $ref: "#/components/schemas/ApiDebugInfo"
      required:
        - id
        - imageUrl
        - prompt
        - style
        - aspectRatio
        - model
        - createdAt
        - apiDebug
    ImageRecord:
      type: object
      properties:
        id:
          type: integer
        imageUrl:
          type: string
        prompt:
          type: string
        style:
          type: string
        aspectRatio:
          type: string
        model:
          type: string
        isPrivate:
          type: boolean
        userId:
          type: integer
          nullable: true
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - imageUrl
        - prompt
        - style
        - aspectRatio
        - model
        - isPrivate
        - createdAt
    ImageHistoryResponse:
      type: object
      properties:
        images:
          type: array
          items:
            $ref: "#/components/schemas/ImageRecord"
        total:
          type: integer
      required:
        - images
        - total
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      required:
        - success
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message