openapi: 3.0.3
info:
  title: VoltageGPU API
  description: |
    VoltageGPU provides OpenAI-compatible endpoints for accessing state-of-the-art AI models.
    
    ## Authentication
    All requests must include an API key in the header:
    ```
    X-VoltageGPU-Key: YOUR_API_KEY
    ```
    
    ## Base URL
    ```
    https://api.voltagegpu.com
    ```
  version: 1.0.0
  contact:
    name: VoltageGPU Support
    email: support@voltagegpu.com
    url: https://voltagegpu.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.voltagegpu.com/v1
    description: Production server
  - url: http://localhost:3000/api/voltage/v1
    description: Local development server

security:
  - ApiKeyAuth: []

paths:
  /chat/completions:
    post:
      summary: Create chat completion
      description: Creates a completion for a chat conversation
      operationId: createChatCompletion
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: Basic chat completion
                value:
                  model: "gpt-4"
                  messages:
                    - role: "system"
                      content: "You are a helpful assistant."
                    - role: "user"
                      content: "Hello!"
              streaming:
                summary: Streaming chat completion
                value:
                  model: "gpt-4"
                  messages:
                    - role: "user"
                      content: "Tell me a story"
                  stream: true
                  temperature: 0.7
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: Server-sent events stream
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /embeddings:
    post:
      summary: Create embeddings
      description: Creates an embedding vector representing the input text
      operationId: createEmbedding
      tags:
        - Embeddings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
            examples:
              single:
                summary: Single text embedding
                value:
                  model: "text-embedding-ada-002"
                  input: "The quick brown fox jumps over the lazy dog"
              multiple:
                summary: Multiple text embeddings
                value:
                  model: "text-embedding-ada-002"
                  input:
                    - "First text to embed"
                    - "Second text to embed"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /images/generations:
    post:
      summary: Create image
      description: Creates an image given a prompt
      operationId: createImage
      tags:
        - Images
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationRequest'
            examples:
              basic:
                summary: Basic image generation
                value:
                  prompt: "A beautiful sunset over mountains"
                  n: 1
                  size: "1024x1024"
              advanced:
                summary: Advanced image generation
                value:
                  prompt: "A futuristic city with flying cars"
                  n: 2
                  size: "512x512"
                  guidance_scale: 7.5
                  num_inference_steps: 50
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-VoltageGPU-Key
      description: Your VoltageGPU API key

  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: ID of the model to use
          example: "gpt-4"
        messages:
          type: array
          description: Messages comprising the conversation
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
          description: Sampling temperature
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Nucleus sampling
        n:
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          description: Number of completions to generate
        stream:
          type: boolean
          default: false
          description: Stream the response
        max_tokens:
          type: integer
          minimum: 1
          description: Maximum tokens to generate
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          description: Presence penalty
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          description: Frequency penalty
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Stop sequences

    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [system, user, assistant]
          description: Role of the message author
        content:
          type: string
          description: Content of the message
        name:
          type: string
          description: Optional name of the author

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
        object:
          type: string
          enum: [chat.completion]
        created:
          type: integer
          description: Unix timestamp
        model:
          type: string
          description: Model used
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
                enum: [stop, length, content_filter, null]
        usage:
          $ref: '#/components/schemas/Usage'

    EmbeddingRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: ID of the model to use
          example: "text-embedding-ada-002"
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Input text to embed

    EmbeddingResponse:
      type: object
      properties:
        object:
          type: string
          enum: [list]
        data:
          type: array
          items:
            type: object
            properties:
              object:
                type: string
                enum: [embedding]
              embedding:
                type: array
                items:
                  type: number
              index:
                type: integer
        model:
          type: string
        usage:
          $ref: '#/components/schemas/Usage'

    ImageGenerationRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: Text prompt for image generation
        n:
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          description: Number of images to generate
        size:
          type: string
          enum: ["256x256", "512x512", "1024x1024", "1792x1024", "1024x1792"]
          default: "1024x1024"
          description: Size of the generated images
        response_format:
          type: string
          enum: [url, b64_json]
          default: url
          description: Format of the response
        guidance_scale:
          type: number
          minimum: 1
          maximum: 20
          default: 7.5
          description: Guidance scale for generation
        num_inference_steps:
          type: integer
          minimum: 10
          maximum: 150
          default: 50
          description: Number of inference steps

    ImageGenerationResponse:
      type: object
      properties:
        created:
          type: integer
          description: Unix timestamp
        data:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                description: URL of the generated image
              b64_json:
                type: string
                description: Base64-encoded JSON of the image

    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Tokens in the prompt
        completion_tokens:
          type: integer
          description: Tokens in the completion
        total_tokens:
          type: integer
          description: Total tokens used

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        details:
          type: object
          properties:
            status:
              type: integer
              description: HTTP status code
            endpoint:
              type: string
              description: Endpoint that caused the error
            plan:
              type: string
              description: User's plan
            attempts:
              type: array
              items:
                type: object
                properties:
                  step:
                    type: string
                  url:
                    type: string
                  status:
                    type: integer
                  latency_ms:
                    type: integer

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Invalid request parameters"
            details:
              status: 400
              endpoint: "/v1/chat/completions"

    Unauthorized:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Invalid or missing API key"
            details:
              status: 401
              endpoint: "/v1/chat/completions"

    Forbidden:
      description: Forbidden - Quota exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Quota exceeded"
            details:
              status: 403
              endpoint: "/v1/chat/completions"
              plan: "free"
              usage:
                tokens_used: 1000
                tokens_limit: 1000

    TooManyRequests:
      description: Too many requests - Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Rate limit exceeded"
            details:
              status: 429
              endpoint: "/v1/chat/completions"
              retry_after: 60

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Internal server error"
            details:
              status: 500
              endpoint: "/v1/chat/completions"

tags:
  - name: Chat
    description: Chat completion endpoints
  - name: Embeddings
    description: Text embedding endpoints
  - name: Images
    description: Image generation endpoints

externalDocs:
  description: VoltageGPU Documentation
  url: https://docs.voltagegpu.com