{
  "openapi": "3.0.3",
  "info": {
    "title": "VibeVoice Public API",
    "description": "Public REST and WebSocket API for VibeVoice real-time speech-to-text streaming, batch audio file transcription, and OAuth device code authentication.",
    "termsOfService": "https://vibevoice.net/terms",
    "contact": {
      "name": "VibeVoice Support",
      "url": "https://vibevoice.net"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://vibevoice.net",
      "description": "Production Server (HTTPS)"
    },
    {
      "url": "wss://vibevoice.net",
      "description": "Production Server (WebSocket)"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/transcribe": {
      "post": {
        "summary": "Batch Audio File Transcription",
        "description": "Synchronous transcription of a single file. The upload is opened as a WAV and nothing transcodes first, so this endpoint accepts WAV only — send any other format to POST /api/jobs/submit. The response body is the transcript as plain text, not JSON.",
        "operationId": "transcribeAudio",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Audio payload. WAV only (PCM, 1-2 channels)."
                  },
                  "initial_prompt": {
                    "type": "string",
                    "description": "Optional decoding hint for this request only — names, jargon or spelling to bias towards. Not a custom vocabulary and not persisted between requests."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transcript, as plain text.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "Hello world, this is a transcribed speech segment."
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key."
          },
          "429": {
            "description": "Quota Exceeded or Rate Limited."
          },
          "413": {
            "description": "File exceeds the plan's maximum upload size."
          },
          "411": {
            "description": "Content-Length header missing — it is required."
          }
        }
      }
    },
    "/api/stream": {
      "get": {
        "summary": "Real-Time WebSocket Streaming Endpoint",
        "description": "Establishes a WebSocket connection for sub-second (<1.0s) streaming speech-to-text with VAD segmentation.",
        "operationId": "streamWebSocket",
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "API Key if not provided in header."
          }
        ],
        "responses": {
          "101": {
            "description": "Switching Protocols to WebSocket"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/oauth/device/code": {
      "post": {
        "summary": "Issue OAuth Device Code",
        "description": "Initiates the OAuth 2.0 Device Code Flow for desktop clients and CLI tools.",
        "operationId": "issueDeviceCode",
        "security": [],
        "responses": {
          "200": {
            "description": "Device Code Issued Successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "device_code": {
                      "type": "string",
                      "example": "dev_code_abc123"
                    },
                    "user_code": {
                      "type": "string",
                      "example": "ABCD-1234"
                    },
                    "verification_uri": {
                      "type": "string",
                      "example": "https://vibevoice.net/link"
                    },
                    "expires_in": {
                      "type": "integer",
                      "example": 900
                    },
                    "interval": {
                      "type": "integer",
                      "example": 5
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/oauth/device/token": {
      "post": {
        "summary": "Exchange OAuth Device Code for Token",
        "description": "Polls device authorization status and retrieves an API key token upon user approval.",
        "operationId": "exchangeDeviceToken",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["device_code"],
                "properties": {
                  "device_code": {
                    "type": "string",
                    "example": "dev_code_abc123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token Exchanged Successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string",
                      "example": "vv_live_key_xyz987"
                    },
                    "token_type": {
                      "type": "string",
                      "example": "Bearer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Authorization Pending or Invalid Code"
          }
        }
      }
    },
    "/api/request-demo-session": {
      "post": {
        "summary": "Request Live Demo Session Token",
        "description": "Generates a temporary session token for in-browser live demo transcription.",
        "operationId": "requestDemoSession",
        "security": [],
        "responses": {
          "200": {
            "description": "Demo Session Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "example": "demo_sess_12345"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}