openapi: 3.0.3
info:
  title: AI Content Generator API
  description: |
    API for generating AI content (text, images, video, audio) with wallet-based billing system.
    
    ## Authentication
    All endpoints require an access token in the Authorization header:
    ```
    Authorization: Bearer YOUR_ACCESS_TOKEN
    ```
    
    ## Pricing
    Quota is deducted from your wallet based on model usage:
    - gpt-4: $0.03 per 1000 tokens
    - gpt-3.5-turbo: $0.002 per 1000 tokens
    - claude-3-opus: $0.015 per 1000 tokens
    - claude-3-sonnet: $0.003 per 1000 tokens
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8600/api/v1
    description: Local development server
  - url: https://api.example.com/v1
    description: Production server

tags:
  - name: Generation
    description: Content generation endpoints
  - name: Requests
    description: Request status and history
  - name: Wallet
    description: Wallet and billing information

paths:
  /generate/text:
    post:
      tags:
        - Generation
      summary: Generate text content
      description: Generate text content using AI models. Quota is automatically deducted from your wallet.
      operationId: generateText
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextGenerationRequest'
            examples:
              simple:
                summary: Simple text generation
                value:
                  prompt: "Write a haiku about programming"
              advanced:
                summary: Advanced with parameters
                value:
                  prompt: "Write a detailed blog post about artificial intelligence"
                  model: "gpt-4"
                  parameters:
                    temperature: 0.7
                    max_tokens: 1000
                    system_prompt: "You are a technical writer"
      responses:
        '200':
          description: Text generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextGenerationResponse'
              example:
                success: true
                request_id: 123
                result: "Code flows like water,\nBugs hide in silent shadows,\nDebug brings the light."
                model: "gpt-4"
                quota_used: 0.0234
                wallet_balance: 9.9766
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/InsufficientBalanceError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/GenerationError'

  /requests/{id}:
    get:
      tags:
        - Requests
      summary: Get request status
      description: Retrieve the status and result of a generation request
      operationId: getRequestStatus
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Request ID
          schema:
            type: integer
            example: 123
      responses:
        '200':
          description: Request details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestStatus'
              example:
                id: 123
                status: "completed"
                prompt: "Write a haiku about programming"
                model: "gpt-4"
                quota_used: 0.0234
                result:
                  text: "Code flows like water..."
                  model: "gpt-4"
                error_message: null
                created_at: "2026-02-08T10:30:00Z"
                updated_at: "2026-02-08T10:30:15Z"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /wallet/balance:
    get:
      tags:
        - Wallet
      summary: Get wallet balance
      description: Retrieve current wallet balance and spending statistics
      operationId: getWalletBalance
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Wallet balance retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBalance'
              example:
                balance: 9.9766
                total_deposited: 10.00
                total_spent: 0.0234
                currency: "USD"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Wallet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "Not Found"
                message: "Wallet not found."

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: |
        Access token for authentication. You can find your token in the admin panel.
        
        Example: `Authorization: Bearer abc123def456...`

  schemas:
    TextGenerationRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 10000
          description: The text prompt for generation
          example: "Write a blog post about artificial intelligence"
        model:
          type: string
          enum:
            - gpt-4
            - gpt-3.5-turbo
            - claude-3-opus
            - claude-3-sonnet
          default: gpt-4
          description: AI model to use for generation
        parameters:
          type: object
          description: Optional generation parameters
          properties:
            temperature:
              type: number
              minimum: 0
              maximum: 1
              default: 0.7
              description: Creativity level (0 = deterministic, 1 = very creative)
              example: 0.7
            max_tokens:
              type: integer
              minimum: 1
              maximum: 4000
              description: Maximum number of tokens to generate
              example: 1000
            system_prompt:
              type: string
              maxLength: 2000
              description: System prompt to guide the model's behavior
              example: "You are a helpful assistant"

    TextGenerationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        request_id:
          type: integer
          description: Unique ID for this generation request
          example: 123
        result:
          type: string
          description: Generated text content
          example: "This is the generated text..."
        model:
          type: string
          description: Model used for generation
          example: "gpt-4"
        quota_used:
          type: number
          format: float
          description: Amount deducted from wallet (in USD)
          example: 0.0234
        wallet_balance:
          type: number
          format: float
          description: Remaining wallet balance (in USD)
          example: 9.9766

    RequestStatus:
      type: object
      properties:
        id:
          type: integer
          example: 123
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Current status of the request
          example: "completed"
        prompt:
          type: string
          description: Original prompt
          example: "Write a haiku"
        model:
          type: string
          description: Model used
          example: "gpt-4"
        quota_used:
          type: number
          format: float
          description: Quota used (in USD)
          example: 0.0234
        result:
          type: object
          nullable: true
          description: Generation result (null if not completed)
          properties:
            text:
              type: string
            model:
              type: string
        error_message:
          type: string
          nullable: true
          description: Error message if failed
          example: null
        created_at:
          type: string
          format: date-time
          example: "2026-02-08T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2026-02-08T10:30:15Z"

    WalletBalance:
      type: object
      properties:
        balance:
          type: number
          format: float
          description: Current balance (in USD)
          example: 9.9766
        total_deposited:
          type: number
          format: float
          description: Total amount deposited (in USD)
          example: 10.00
        total_spent:
          type: number
          format: float
          description: Total amount spent (in USD)
          example: 0.0234
        currency:
          type: string
          description: Currency code
          example: "USD"

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error type
          example: "Validation Error"
        message:
          type: string
          description: Human-readable error message
          example: "The prompt field is required."
        details:
          type: string
          description: Additional error details
          example: "Field validation failed"

    ValidationError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            errors:
              type: object
              description: Field-specific validation errors
              additionalProperties:
                type: array
                items:
                  type: string

  responses:
    UnauthorizedError:
      description: Authentication failed - invalid or missing access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Unauthorized"
            message: "Invalid access token."

    InsufficientBalanceError:
      description: Insufficient wallet balance
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  required_quota:
                    type: number
                    format: float
                  current_balance:
                    type: number
                    format: float
          example:
            error: "Insufficient Balance"
            message: "Your wallet does not have enough balance for this request."
            required_quota: 0.05
            current_balance: 0.02

    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            error: "Validation Error"
            message: "The given data was invalid."
            errors:
              prompt:
                - "The prompt field is required."

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Not Found"
            message: "Request not found or does not belong to you."

    GenerationError:
      description: Content generation failed (quota refunded)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Generation Failed"
            message: "Failed to generate content. Quota has been refunded."
            details: "Model timeout error"

security:
  - BearerAuth: []
