{ "openapi": "3.1.0", "info": { "title": "Audinote public audio HTTP API", "version": "1.0.0", "description": "Source-backed Audinote aliases and JSON audio contract. Not a general OpenAI/OpenRouter passthrough. All HTTP operations require bearer keys and consume shared rate allowance (60/key/minute, 120/user/minute). State-changing audio operations spend existing minute credits. Catalog depends on operation-specific routing/secrets; fixture verification does not establish live provider access. WebSocket protocols are documented separately at /developers and in docs/public-api.md. Source: apps/worker/src/routes/public-audio.ts and speech-jobs.ts." }, "servers": [ { "url": "https://audinote.app/api/v1", "description": "Production API origin; availability depends on current configuration." } ], "security": [ { "AudinoteBearer": [] } ], "tags": [ { "name": "Audio API" } ], "paths": { "/models": { "get": { "operationId": "listModels", "summary": "List configured Audinote model aliases", "tags": [ "Audio API" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "413": { "$ref": "#/components/responses/Error413" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/voices": { "get": { "operationId": "listVoices", "summary": "List configured Audinote voice aliases", "tags": [ "Audio API" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "413": { "$ref": "#/components/responses/Error413" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/audio/transcriptions": { "post": { "operationId": "transcribeAudio", "summary": "Transcribe a bounded WAV synchronously", "tags": [ "Audio API" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcription" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "413": { "$ref": "#/components/responses/Error413" }, "500": { "$ref": "#/components/responses/Error500" } }, "description": "Spends Audinote credits. JSON only; multipart and provider passthrough are unsupported. async_required when configured file route needs jobs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsrRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/audio/speech": { "post": { "operationId": "generateSpeech", "summary": "Generate speech audio", "tags": [ "Audio API" ], "responses": { "200": { "description": "Raw audio, <=8 MiB. Only currently advertised formats are accepted.", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } }, "X-Audinote-Billed-Minutes": { "description": "Charged Audinote minute credits, despite header name.", "schema": { "type": "number", "minimum": 0 } } }, "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "413": { "$ref": "#/components/responses/Error413" }, "500": { "$ref": "#/components/responses/Error500" } }, "description": "Spends credits per started 1000 Unicode characters at the pinned route rate. Actual bytes/MIME match selected supported output.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/audio/transcription-jobs": { "post": { "operationId": "createTranscriptionJob", "summary": "Submit an asynchronous transcription job", "tags": [ "Audio API" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "413": { "$ref": "#/components/responses/Error413" }, "500": { "$ref": "#/components/responses/Error500" } }, "description": "Requires asynchronous file route. Credits held before processing; results retained 24 hours. Do not automatically resubmit ambiguous provider work.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/audio/transcription-jobs/{id}": { "get": { "operationId": "getTranscriptionJob", "summary": "Read a transcription job with its creating key", "tags": [ "Audio API" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatus" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "413": { "$ref": "#/components/responses/Error413" }, "500": { "$ref": "#/components/responses/Error500" } }, "description": "Same API key required, even for another key of the same user. Expired jobs return 404; polling consumes rate allowance.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/realtime/tickets": { "post": { "operationId": "createRealtimeTicket", "summary": "Create a one-use browser WebSocket ticket", "tags": [ "Audio API" ], "responses": { "201": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "413": { "$ref": "#/components/responses/Error413" }, "500": { "$ref": "#/components/responses/Error500" } }, "description": "Ticket expires after 60 seconds, is route-kind bound and consumed atomically during upgrade. Pass in audinote-ticket. WebSocket subprotocol; never in URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRequest" } } } } } } }, "components": { "securitySchemes": { "AudinoteBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "aud_<43 base64url characters>", "description": "Active owner API key created at /account/api; cookies alone do not authorize these routes." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "server_error" ] } }, "required": [ "code", "message", "type" ] }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ] }, "GlobalError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "settings": { "type": "array", "items": { "type": "string" } } }, "required": [ "error", "code" ] }, "InputAudio": { "type": "object", "properties": { "data": { "type": "string", "description": "Raw base64, without data: prefix, of mono PCM16 WAV at 16000 or 24000 Hz. Decoded size <=20 MiB, duration <=600 seconds and selected model ceiling." }, "format": { "type": "string", "const": "wav" } }, "required": [ "data", "format" ], "additionalProperties": false }, "AsrRequest": { "type": "object", "properties": { "model": { "type": "string", "const": "audinote-asr-v1" }, "input_audio": { "$ref": "#/components/schemas/InputAudio" }, "language": { "type": "string", "enum": [ "th", "en" ] }, "response_format": { "type": "string", "enum": [ "json", "verbose_json" ], "default": "json" } }, "required": [ "model", "input_audio" ], "additionalProperties": false }, "JobRequest": { "type": "object", "properties": { "model": { "type": "string", "const": "audinote-asr-v1" }, "input_audio": { "$ref": "#/components/schemas/InputAudio" }, "language": { "type": "string", "enum": [ "th", "en" ] } }, "required": [ "model", "input_audio" ], "additionalProperties": false }, "SpeechRequest": { "type": "object", "properties": { "model": { "type": "string", "const": "audinote-tts-v1" }, "input": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "1–2000 Unicode code points." }, "voice": { "type": "string", "enum": [ "sai-th", "rin-en" ] }, "response_format": { "type": "string", "enum": [ "mp3", "wav" ], "default": "mp3", "description": "Must be advertised by the current model catalog." } }, "required": [ "model", "input", "voice" ], "additionalProperties": false }, "Segment": { "type": "object", "properties": { "text": { "type": "string" }, "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 }, "speaker": { "type": [ "string", "null" ], "description": "Public speaker alias; null when no diarization." }, "timing": { "type": "string", "enum": [ "provider", "chunk" ] } }, "required": [ "text", "start", "end", "speaker", "timing" ] }, "Usage": { "type": "object", "properties": { "audio_seconds": { "type": "number", "minimum": 0 }, "billed_minutes": { "type": "number", "minimum": 0 } }, "required": [ "audio_seconds", "billed_minutes" ] }, "Transcription": { "type": "object", "properties": { "text": { "type": "string" }, "model": { "type": "string", "const": "audinote-asr-v1" }, "usage": { "$ref": "#/components/schemas/Usage" }, "duration": { "type": "number", "minimum": 0 }, "language": { "type": [ "string", "null" ], "enum": [ "th", "en", null ] }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } }, "required": [ "text", "model", "usage" ], "description": "duration/language/segments appear only for verbose_json." }, "JobAccepted": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "model": { "type": "string", "const": "audinote-asr-v1" }, "status_url": { "type": "string" } }, "required": [ "id", "status", "model" ], "description": "Initial creation has status_url; existing-job idempotent replay may omit it." }, "JobStatus": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "model": { "type": "string", "const": "audinote-asr-v1" }, "code": { "type": "string", "const": "transcription_failed" }, "text": { "type": "string" }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "usage": { "type": "object", "properties": { "audio_seconds": { "type": "number", "minimum": 0 }, "billed_minutes": { "type": "number", "minimum": 0 }, "billing_status": { "type": "string", "enum": [ "settled", "pending" ] } }, "required": [ "audio_seconds", "billed_minutes", "billing_status" ] } }, "required": [ "id", "status", "model" ], "description": "Completed status includes text, segments and usage. Failed status includes code. Pending includes only identity/status/model." }, "Model": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "audinote-asr-v1", "audinote-tts-v1" ] }, "object": { "type": "string", "const": "model" }, "input_modalities": { "type": "array", "items": { "type": "string", "enum": [ "audio", "text" ] } }, "output_modalities": { "type": "array", "items": { "type": "string", "enum": [ "audio", "text" ] } }, "formats": { "type": "array", "items": { "type": "string" } }, "operations": { "type": "array", "items": { "type": "string", "enum": [ "file-asr", "realtime-asr", "tts", "realtime-tts" ] } }, "file_mode": { "type": [ "string", "null" ], "enum": [ "sync", "async", null ] }, "max_file_seconds": { "type": [ "number", "null" ] } }, "required": [ "id", "object", "input_modalities", "output_modalities", "formats", "operations" ], "description": "Only available aliases are returned. file_mode and max_file_seconds are ASR-only. Formats describe configured file/TTS operation, not WebSocket PCM encoding." }, "Voice": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "sai-th", "rin-en" ] }, "name": { "type": "string" }, "language": { "type": "string", "enum": [ "th", "en" ] }, "model": { "type": "string", "const": "audinote-tts-v1" } }, "required": [ "id", "name", "language", "model" ] }, "TicketRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "asr", "tts" ] } }, "required": [ "kind" ] }, "Ticket": { "type": "object", "properties": { "ticket": { "type": "string", "pattern": "^audrt_[A-Za-z0-9_-]{43}$" }, "expires_in": { "type": "integer", "const": 60 } }, "required": [ "ticket", "expires_in" ] } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._-]+$" }, "description": "Scoped to creating key and endpoint. Synchronous repeats return 409 (no replay); asynchronous repeats return existing ID/status with 202." } }, "responses": { "Error401": { "description": "Invalid, revoked or unavailable key.", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Rate, quota or concurrency limit.", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Routed service unavailable/billing pending, or pre-route service configuration failure (top-level code/settings).", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/GlobalError" } ] } } } }, "Error413": { "description": "Payload exceeds pre-route ceiling (top-level error/code, not routed envelope).", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalError" } } } }, "Error500": { "description": "Uncaught application failure uses the top-level global error/code shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalError" } } } }, "Error400": { "description": "Invalid input, format or operation.", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error402": { "description": "Insufficient credits.", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "Duplicate request.", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error502": { "description": "Processing failed.", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Unknown, expired or foreign-key job.", "headers": { "X-Request-Id": { "description": "Public request identifier.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "externalDocs": { "url": "https://audinote.app/developers", "description": "HTTP examples and separately documented WebSocket event protocols" }, "x-websocket-endpoints": [ "/api/v1/realtime/asr", "/api/v1/realtime/tts" ] }