{"openapi":"3.1.0","info":{"title":"AiVoxta Speech Studio & Agent Voice API","version":"1.0.0","description":"Official OpenAPI 3.1.0 specification for AiVoxta.\n\n### API Versioning Policy\nAiVoxta uses URL path versioning (`/api/v1/`) alongside unversioned canonical aliases (`/api/`). Every response includes the `X-API-Version: 1.0.0` header.\n\n### Deprecation & Sunset Policy\nAiVoxta adheres to RFC 8594 / RFC 9110 deprecation standards. When an endpoint or version is scheduled for retirement, responses include `Deprecation: @<unix-timestamp>` and `Sunset: <http-date>` headers with at least 180 days advance notice.\n\n### Rate Limiting Conventions\nAll API responses return IETF draft RateLimit headers:\n- `RateLimit-Limit`: Maximum requests per window (default 60)\n- `RateLimit-Remaining`: Remaining requests in current window\n- `RateLimit-Reset`: Window reset countdown in seconds\n- `RateLimit-Policy`: Quota specification (e.g. 60;w=60)\n- `Retry-After`: Returned on HTTP 429 indicating seconds to pause\n\n### Typed Error Model (RFC 9457)\nAll 4xx and 5xx responses return structured `application/problem+json` with machine-readable `code`, human-readable `message`, and actionable `resolution` hints.","contact":{"name":"AiVoxta Developer Support","email":"support@voxta.ai","url":"https://aivoxta.vercel.app/contact"},"license":{"name":"MIT"}},"servers":[{"url":"https://aivoxta.vercel.app","description":"Production Server"}],"paths":{"/api/v1/tts":{"post":{"summary":"Synthesize Neural Speech (v1)","description":"Synthesizes studio-quality speech audio from text using Fish Audio S2.1 with inline emotion tags (e.g. [whispering], [excited], [dramatic]).","operationId":"synthesizeSpeechV1","security":[{"FishApiKey":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTSRequest"}}}},"responses":{"200":{"description":"Synthesized binary audio stream.","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"summary":"Get Speech Endpoint Info (v1)","description":"Returns schema, authentication requirements, and capabilities for the speech synthesis endpoint.","operationId":"getTtsInfoV1","responses":{"200":{"description":"Endpoint capability metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsEndpointInfo"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tts":{"post":{"summary":"Synthesize Neural Speech","description":"Canonical unversioned alias for /api/v1/tts. Synthesizes studio-quality speech audio from text using Fish Audio S2.1 with inline emotion tags.","operationId":"synthesizeSpeech","security":[{"FishApiKey":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTSRequest"}}}},"responses":{"200":{"description":"Synthesized binary audio stream.","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"summary":"Get Speech Endpoint Info","description":"Canonical unversioned alias. Returns endpoint schema, authentication requirements, and capabilities.","operationId":"getTtsInfo","responses":{"200":{"description":"Endpoint capability metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsEndpointInfo"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/voices":{"get":{"summary":"List Available Neural Voices (v1)","description":"Returns curated and dynamic voices with language and category attributes.","operationId":"listVoicesV1","responses":{"200":{"description":"Array of voices and directory metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoicesResponse"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/voices":{"get":{"summary":"List Available Neural Voices","description":"Canonical alias. Returns curated and dynamic voices with language and category attributes.","operationId":"listVoices","responses":{"200":{"description":"Array of voices and directory metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoicesResponse"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/enhance":{"post":{"summary":"Enhance Script with Emotion Tags (v1)","description":"Automatically annotates plain text scripts with natural emotion tags ([whisper], [excited], [dramatic]) for S2.1 performance.","operationId":"enhancePromptV1","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnhanceRequest"}}}},"responses":{"200":{"description":"Annotated script text with performance tags.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnhanceResponse"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/enhance":{"post":{"summary":"Enhance Script with Emotion Tags","description":"Canonical alias. Automatically annotates plain text scripts with natural emotion tags for S2.1 performance.","operationId":"enhancePrompt","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnhanceRequest"}}}},"responses":{"200":{"description":"Annotated script text with performance tags.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnhanceResponse"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/wallet":{"get":{"summary":"Query Fish Audio Wallet & Credits (v1)","description":"Inspects active API credit balance and subscription tier.","operationId":"checkWalletV1","security":[{"FishApiKey":[]}],"responses":{"200":{"description":"Account balance information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletResponse"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/wallet":{"get":{"summary":"Query Fish Audio Wallet & Credits","description":"Canonical alias. Inspects active API credit balance and subscription tier.","operationId":"checkWallet","security":[{"FishApiKey":[]}],"responses":{"200":{"description":"Account balance information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletResponse"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/.well-known/mcp":{"get":{"summary":"Model Context Protocol (MCP) Manifest & SSE Handshake","description":"Returns server capabilities, tool schemas, transport details, and supports SSE streaming live handshake.","operationId":"getMcpManifest","responses":{"200":{"description":"MCP manifest or live SSE stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpManifestResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Model Context Protocol (MCP) JSON-RPC Endpoint","description":"Executes MCP tools and initialization handshakes (Streamable HTTP / JSON-RPC 2.0).","operationId":"postMcpRpc","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response with tool output or initialization status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcResponse"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/.well-known/mcp.json":{"get":{"summary":"Model Context Protocol (MCP) JSON Manifest File","description":"Direct static alias returning the MCP manifest JSON structure for agent discoverability.","operationId":"getMcpManifestJson","responses":{"200":{"description":"MCP manifest structure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpManifestResponse"}}}},"400":{"description":"Bad Request - Validation or JSON parsing failed (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key credentials (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - The requested resource or voice ID was not found (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded. Check Retry-After and RateLimit headers (RFC 9457).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before making a new request."}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Unexpected error in the synthesis pipeline (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"FishApiKey":{"type":"apiKey","in":"header","name":"x-fish-api-key","description":"Fish Audio personal API key (BYOK)."},"BearerAuth":{"type":"http","scheme":"bearer","description":"Fish Audio personal API key via Bearer token."}},"schemas":{"ErrorResponse":{"type":"object","required":["code","error"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference identifying problem type (RFC 9457).","example":"https://aivoxta.vercel.app/docs#error-missing_api_key"},"title":{"type":"string","description":"Short human-readable summary of problem.","example":"API Key Required"},"status":{"type":"integer","description":"HTTP status code.","example":401},"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","QUOTA_EXCEEDED","RATE_LIMITED","MODEL_NOT_FOUND","NETWORK_OFFLINE","REQUEST_TIMEOUT","VALIDATION_FAILED","NOT_FOUND","METHOD_NOT_ALLOWED","SERVER_ERROR"],"description":"Machine-readable application error code.","example":"MISSING_API_KEY"},"error":{"type":"string","description":"Error explanation.","example":"Fish Audio API key is missing."},"message":{"type":"string","description":"Human-readable message.","example":"Fish Audio API key is missing."},"detail":{"type":"string","description":"Detailed error explanation.","example":"Pass your Fish Audio API key via the x-fish-api-key header."},"resolution":{"type":"string","description":"Actionable resolution hint for automated agents.","example":"Pass your Fish Audio API key via the x-fish-api-key header. Obtain a free key at https://fish.audio/app/api-keys."},"details":{"type":"object","description":"Optional validation details or error list."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence of the problem.","example":"/api/tts"}}},"TTSRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"Script to synthesize, supporting inline tags like [whispering], [dramatic].","example":"[excited] Welcome to AiVoxta. The future of neural speech is here."},"voice_id":{"type":"string","description":"Voice preset ID or 32-character custom Fish Audio model ID.","default":"hindi-female","example":"hindi-female"},"format":{"type":"string","enum":["mp3","wav","pcm"],"default":"mp3"},"temperature":{"type":"number","minimum":0.1,"maximum":1,"default":0.7,"description":"Acoustic variability and cadence."},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1,"description":"Playback speed multiplier."},"apiKey":{"type":"string","description":"Optional client Fish Audio key if not sent via headers."}}},"TtsEndpointInfo":{"type":"object","required":["name","endpoint","method"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"endpoint":{"type":"string"},"versionedEndpoint":{"type":"string"},"method":{"type":"string"},"description":{"type":"string"},"requestBodySchema":{"type":"object"},"authentication":{"type":"string"},"openapi":{"type":"string"},"documentation":{"type":"string"}}},"VoicesResponse":{"type":"object","required":["voices","defaultVoiceId","languages","categories"],"properties":{"voices":{"type":"array","items":{"$ref":"#/components/schemas/VoiceItem"}},"defaultVoiceId":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}}}},"VoiceItem":{"type":"object","required":["id","name","language","category"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"gender":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}},"EnhanceRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"Raw dialogue text to annotate with performance cues.","example":"Listen closely. Everything changed at that moment."},"model":{"type":"string","description":"Optional OpenRouter LLM model ID or rule-based tagger."},"apiKey":{"type":"string","description":"Optional OpenRouter API key."}}},"EnhanceResponse":{"type":"object","required":["enhancedText","model"],"properties":{"enhancedText":{"type":"string","description":"Text annotated with performance brackets.","example":"[whisper] Listen closely. [dramatic] Everything changed at that moment."},"model":{"type":"string","description":"Model or algorithm that generated the tags."}}},"WalletResponse":{"type":"object","required":["live"],"properties":{"live":{"type":"boolean"},"credit":{"type":"number"},"packageTotal":{"type":"number"},"packageBalance":{"type":"number"},"packageType":{"type":"string"},"hasFreeCredit":{"type":"boolean"}}},"McpManifestResponse":{"type":"object","required":["mcpVersion","protocolVersion","serverInfo","capabilities","tools","transport"],"properties":{"mcpVersion":{"type":"string","example":"2024-11-05"},"protocolVersion":{"type":"string","example":"2024-11-05"},"serverInfo":{"type":"object","required":["name","version"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"}}},"capabilities":{"type":"object","properties":{"tools":{"type":"object"},"resources":{"type":"object"},"prompts":{"type":"object"}}},"transport":{"type":"object","properties":{"type":{"type":"string"},"endpoint":{"type":"string"},"sseEndpoint":{"type":"string"},"streamable":{"type":"boolean"}}},"tools":{"type":"array","items":{"type":"object"}}}},"McpJsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string","enum":["initialize","notifications/initialized","ping","tools/list","tools/call"],"description":"MCP JSON-RPC method to execute."},"params":{"type":"object","description":"Method parameters (e.g. tool name and arguments)."}}},"McpJsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"result":{"type":"object","description":"RPC result payload."},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object"}}}}}}}}