{"openapi":"3.1.0","info":{"title":"CastReader Voice API","version":"0.1.0-preview","description":"International region only. Implemented preview contracts. Features remain gated by deployment configuration. An admission pause rejects new work with 503 admission_paused while reads and completed speech replays remain available; disabling the whole service returns 404. Configuration does not attest worker health. This specification does not establish a production endpoint, SLA, live billing availability or measured GPU performance. USD pricing is $12 per million normalized Unicode code points."},"servers":[{"url":"https://voice.castreader.com/v1","description":"Configured deployment base; local default is for development only."}],"security":[{"DeveloperApiKey":[]}],"paths":{"/route":{"get":{"operationId":"resolveRoute","summary":"Select a regional endpoint without uploading text or audio","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"region":{"enum":["cn","us"]},"network_region":{"enum":["cn","us"]},"base_url":{"type":"string"},"console_url":{"type":"string"},"expires_in":{"type":"integer","minimum":0},"voice_data_failover":{"const":false},"languages":{"type":"array","items":{"type":"string"}}},"required":["region","network_region","base_url","console_url","expires_in","voice_data_failover","languages"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"voice_id","in":"query","required":false,"schema":{"type":"string"},"description":"At most one resource ID. Existing tasks remain in their original region."},{"name":"request_id","in":"query","required":false,"schema":{"type":"string"},"description":"At most one resource ID. Existing tasks remain in their original region."},{"name":"job_id","in":"query","required":false,"schema":{"type":"string"},"description":"At most one resource ID. Existing tasks remain in their original region."}]}},"/health":{"get":{"operationId":"health","summary":"Read the enabled service identity","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"const":"castreader-voice-api"},"region":{"enum":["global","cn"]},"status":{"enum":["invitation-preview","developer-preview"]},"model_revision":{"type":"string"}},"required":["service","region","status","model_revision"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"security":[]}},"/models":{"get":{"operationId":"listModels","summary":"Read current model revision, languages, formats and short-request limit","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/audio/speech":{"post":{"operationId":"createSpeech","summary":"Generate complete audio, or an NDJSON stream when stream=true","x-required-scopes":["speech:generate"],"responses":{"200":{"description":"Private audio. Replays return the original retained result without another charge. PCM results use signed 16-bit little-endian mono samples at 24 kHz.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Model-Revision":{"schema":{"type":"string"}},"X-Voice-Version":{"schema":{"type":"string"}},"X-Billable-Characters":{"schema":{"type":"string"}},"X-Trial-Characters":{"schema":{"type":"string"}},"X-Charged-USD":{"schema":{"type":"string"}},"X-Idempotency-Replayed":{"schema":{"type":"string"}},"X-Result-Expires-At":{"schema":{"type":"string"}},"X-Timestamps-URL":{"schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"application/x-ndjson":{"schema":{"type":"string"},"x-event-schema":{"$ref":"#/components/schemas/SpeechStreamEvent"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable logical-operation key. Reuse for identical retries; never generate a new key automatically after an ambiguous timeout.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SpeechInput"},{"type":"object","properties":{"model":{"type":"string","const":"clone-v1"},"voice_id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"text":{"type":"string","minLength":1,"description":"Normalize CRLF to LF, normalize Unicode NFC, trim, then count Unicode code points. Current short-request limit: 120."},"language":{"type":"string","enum":["en"],"default":"en"},"output_format":{"type":"string","const":"pcm_s16le","default":"pcm_s16le"},"speed":{"type":"number","const":1,"default":1},"stream":{"type":"boolean","const":true,"default":true},"return_timestamps":{"type":"boolean","const":false,"default":false}},"required":["model","voice_id","text","stream"],"additionalProperties":false}]}}}}}},"/audio/stream":{"post":{"operationId":"streamSpeech","summary":"Generate incremental PCM as NDJSON events","x-required-scopes":["speech:generate"],"responses":{"200":{"description":"Newline-delimited JSON. Each audio.audio field is base64 PCM. A start followed by zero or more audio events must end with done; error or EOF without done is not successful completion.","content":{"application/x-ndjson":{"schema":{"type":"string"},"x-event-schema":{"$ref":"#/components/schemas/SpeechStreamEvent"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable logical-operation key. Reuse for identical retries; never generate a new key automatically after an ambiguous timeout.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreamInput"}}}},"x-enabled":false}},"/voices":{"get":{"operationId":"listVoices","summary":"Page through authorized private voices, newest first","x-required-scopes":["voices:read"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceList"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":512},"description":"Opaque next_cursor from the previous page. Do not decode, edit or construct cursors."}],"description":"Returns data, has_more and nullable next_cursor. Ordering is descending creation time, then descending voice ID. Every page rechecks project and voice access."},"post":{"operationId":"registerVoice","summary":"Record voice permission and queue private voice processing","x-required-scopes":["voices:write"],"responses":{"202":{"description":"Registration accepted; wait for status=ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable logical-operation key. Reuse for identical retries; never generate a new key automatically after an ambiguous timeout.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/VoiceRegistration"}}}},"description":"A voice-restricted key cannot register a new voice. Uploading audio requires explicit speaker authorization. Each workspace allows two active voices and 5 new registrations per UTC day; exceeding either returns 429 voice_registration_limit. Processing and deleting voices count as active. Deleting a voice does not restore the daily registration allowance."}},"/voices/{voice_id}":{"get":{"operationId":"getVoice","summary":"Read one authorized voice","x-required-scopes":["voices:read"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"voice_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"operationId":"renameVoice","summary":"Change only the voice display name","x-required-scopes":["voices:write"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"voice_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"],"additionalProperties":false}}}}},"delete":{"operationId":"deleteVoice","summary":"Revoke voice access and queue private artifact deletion","x-required-scopes":["voices:write"],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"voice_id","in":"path","required":true,"schema":{"type":"string"}}],"description":"New synthesis and retained downloads are blocked when voice permission is revoked. Physical cleanup is asynchronous."}},"/voices/{voice_id}/preview":{"get":{"operationId":"getVoicePreview","summary":"Download an available ready voice preview","x-required-scopes":["voices:read"],"responses":{"200":{"description":"Private MP3 preview.","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"voice_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/requests/{request_id}":{"get":{"operationId":"getSpeechRequest","summary":"Read status and the original metering receipt","x-required-scopes":["speech:generate"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechRequest"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/requests/{request_id}/timestamps":{"get":{"operationId":"getSpeechTimestamps","summary":"Read retained v3 audio alignment without regeneration","x-required-scopes":["speech:generate"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechTimestamps"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires current project and voice access. Opt in at generation with return_timestamps: true. Returns 404 when not requested, 409 before completion, 410 after retention. status unavailable contains no guessed words; successful audio remains charged once. Times are seconds relative to this audio file, including for each job chunk."}},"/requests/{request_id}/audio":{"get":{"operationId":"getSpeechAudio","summary":"Download retained MP3, WAV or stream PCM for a successful request","x-required-scopes":["speech:generate"],"responses":{"200":{"description":"Private audio. Replays return the original retained result without another charge. PCM results use signed 16-bit little-endian mono samples at 24 kHz.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Model-Revision":{"schema":{"type":"string"}},"X-Voice-Version":{"schema":{"type":"string"}},"X-Billable-Characters":{"schema":{"type":"string"}},"X-Trial-Characters":{"schema":{"type":"string"}},"X-Charged-USD":{"schema":{"type":"string"}},"X-Idempotency-Replayed":{"schema":{"type":"string"}},"X-Result-Expires-At":{"schema":{"type":"string"}},"X-Timestamps-URL":{"schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/pcm":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires current project and voice access. Expired results return 410. No public result URL is issued."}},"/usage":{"get":{"operationId":"getUsage","summary":"Read current UTC month usage and up to 20 recent requests","x-required-scopes":["usage:read"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/usage/estimate":{"post":{"operationId":"estimateSpeech","summary":"Estimate normalized characters and cost without reserving funds","x-required-scopes":["speech:generate"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateInput"}}}},"description":"Requires an authorized ready voice. Trial estimates include current daily allowance and reservations; estimates can change before generation."}},"/billing/balance":{"get":{"operationId":"getBillingBalance","summary":"Read the owner wallet or a member key’s project budget summary","x-required-scopes":["usage:read"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Wallet"},{"$ref":"#/components/schemas/ProjectBalance"}]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/balance":{"get":{"operationId":"getBalanceAlias","summary":"Read the owner wallet or a member key’s project budget summary","x-required-scopes":["usage:read"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Wallet"},{"$ref":"#/components/schemas/ProjectBalance"}]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"x-alias-of":"/billing/balance"}},"/audio/jobs":{"post":{"operationId":"createAudioJob","summary":"Queue a durable job with ordered, individually billed chunks","x-required-scopes":["speech:generate"],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable logical-operation key. Reuse for identical retries; never generate a new key automatically after an ambiguous timeout.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","const":"clone-v1"},"voice_id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"text":{"type":"string","minLength":1,"description":"Normalize CRLF to LF, normalize Unicode NFC, trim, then count Unicode code points. Current queued source limit: 120; each generated chunk uses up to 120 characters."},"language":{"type":"string","enum":["en"],"default":"en"},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3"},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1,"description":"MP3: 0.5–2. WAV and streaming require 1."},"stream":{"type":"boolean","const":false,"default":false},"return_timestamps":{"type":"boolean","default":false,"description":"English only (language=en). Omit for Chinese, Japanese and other languages; true with a non-English language returns 422 unsupported_timestamps before generation or billing. Opt in to v3 word or measured word-group alignment. Audio stays binary. Read metadata at the X-Timestamps-URL or request receipt timestamps_url; no extra alignment charge. May return unavailable without failing the audio."}},"required":["model","voice_id","text"],"additionalProperties":false,"description":"Queued speech must have stream=false. Configured maximum: 120 normalized source characters; chunks use up to 120 characters each. Task deadline: 600 seconds. Waiting is free; successful chunks are billed once. The response intentionally uses camelCase fields."}}}},"x-enabled":true}},"/audio/jobs/{job_id}":{"get":{"operationId":"getAudioJob","summary":"Read job progress, per-chunk request IDs and charges","x-required-scopes":["speech:generate"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"x-enabled":true},"delete":{"operationId":"cancelAudioJob","summary":"Request cancellation; completed chunks retain their charges","x-required-scopes":["speech:generate"],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"x-enabled":true}},"/audio/jobs/{job_id}/cancel":{"post":{"operationId":"cancelAudioJobByPost","summary":"Request cancellation; completed chunks retain their charges","x-required-scopes":["speech:generate"],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"x-enabled":true}},"/jobs":{"post":{"operationId":"createJobAlias","summary":"Queue a durable job with ordered, individually billed chunks","x-required-scopes":["speech:generate"],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable logical-operation key. Reuse for identical retries; never generate a new key automatically after an ambiguous timeout.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","const":"clone-v1"},"voice_id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"text":{"type":"string","minLength":1,"description":"Normalize CRLF to LF, normalize Unicode NFC, trim, then count Unicode code points. Current queued source limit: 120; each generated chunk uses up to 120 characters."},"language":{"type":"string","enum":["en"],"default":"en"},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3"},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1,"description":"MP3: 0.5–2. WAV and streaming require 1."},"stream":{"type":"boolean","const":false,"default":false},"return_timestamps":{"type":"boolean","default":false,"description":"English only (language=en). Omit for Chinese, Japanese and other languages; true with a non-English language returns 422 unsupported_timestamps before generation or billing. Opt in to v3 word or measured word-group alignment. Audio stays binary. Read metadata at the X-Timestamps-URL or request receipt timestamps_url; no extra alignment charge. May return unavailable without failing the audio."}},"required":["model","voice_id","text"],"additionalProperties":false,"description":"Queued speech must have stream=false. Configured maximum: 120 normalized source characters; chunks use up to 120 characters each. Task deadline: 600 seconds. Waiting is free; successful chunks are billed once. The response intentionally uses camelCase fields."}}}},"x-enabled":true,"x-alias-of":"/audio/jobs"}},"/jobs/{job_id}":{"get":{"operationId":"getJobAlias","summary":"Read job progress, per-chunk request IDs and charges","x-required-scopes":["speech:generate"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"x-enabled":true},"delete":{"operationId":"cancelJobAlias","summary":"Request cancellation; completed chunks retain their charges","x-required-scopes":["speech:generate"],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"x-enabled":true}},"/jobs/{job_id}/cancel":{"post":{"operationId":"cancelJobByPostAlias","summary":"Request cancellation; completed chunks retain their charges","x-required-scopes":["speech:generate"],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"x-enabled":true}},"/realtime/sessions":{"post":{"operationId":"createRealtimeSession","summary":"Create a short-lived, one-use realtime connection token","x-required-scopes":["speech:generate"],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeSession"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"499":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeSessionInput"}}}},"x-enabled":false,"description":"At most two pending or active sessions per workspace. This endpoint creates a connection authorization, not an audio charge. Committed text segments use the speech ledger. Session creation has no idempotency deduplication; sending an Idempotency-Key does not make a new call reuse an existing session."}}},"components":{"securitySchemes":{"DeveloperApiKey":{"type":"http","scheme":"bearer","bearerFormat":"cr_live_key_<public-id>_<secret>","description":"Server-only project key. Scopes: speech:generate, voices:read, voices:write, usage:read. Key creator membership and canonical account availability are rechecked."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":true}},"required":["code","message","request_id","retryable"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"SpeechInput":{"type":"object","properties":{"model":{"type":"string","const":"clone-v1"},"voice_id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"text":{"type":"string","minLength":1,"description":"Normalize CRLF to LF, normalize Unicode NFC, trim, then count Unicode code points. Current short-request limit: 120."},"language":{"type":"string","enum":["en"],"default":"en"},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3"},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1,"description":"MP3: 0.5–2. WAV and streaming require 1."},"stream":{"type":"boolean","const":false,"default":false},"return_timestamps":{"type":"boolean","default":false,"description":"English only (language=en). Omit for Chinese, Japanese and other languages; true with a non-English language returns 422 unsupported_timestamps before generation or billing. Opt in to v3 word or measured word-group alignment. Audio stays binary. Read metadata at the X-Timestamps-URL or request receipt timestamps_url; no extra alignment charge. May return unavailable without failing the audio."}},"required":["model","voice_id","text"],"additionalProperties":false},"StreamInput":{"type":"object","properties":{"model":{"type":"string","const":"clone-v1"},"voice_id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"text":{"type":"string","minLength":1,"description":"Normalize CRLF to LF, normalize Unicode NFC, trim, then count Unicode code points. Current short-request limit: 120."},"language":{"type":"string","enum":["en"],"default":"en"},"output_format":{"type":"string","const":"pcm_s16le","default":"pcm_s16le"},"speed":{"type":"number","const":1,"default":1},"stream":{"type":"boolean","const":true,"default":true},"return_timestamps":{"type":"boolean","const":false,"default":false}},"required":["model","voice_id","text"],"additionalProperties":false},"EstimateInput":{"type":"object","properties":{"model":{"type":"string","const":"clone-v1"},"voice_id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"text":{"type":"string","minLength":1,"description":"Normalize CRLF to LF, normalize Unicode NFC, trim, then count Unicode code points. Current short-request limit: 120."},"language":{"type":"string","enum":["en"],"default":"en"},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3"},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1,"description":"MP3: 0.5–2. WAV and streaming require 1."},"stream":{"type":"boolean","default":false,"description":"When true, the deployment must enable streaming. Estimates still return JSON and create no audio."},"return_timestamps":{"type":"boolean","default":false,"description":"English only (language=en). Omit for Chinese, Japanese and other languages; true with a non-English language returns 422 unsupported_timestamps before generation or billing. Opt in to v3 word or measured word-group alignment. Audio stays binary. Read metadata at the X-Timestamps-URL or request receipt timestamps_url; no extra alignment charge. May return unavailable without failing the audio."}},"required":["model","voice_id","text"],"additionalProperties":false},"SpeechTimestamps":{"type":"object","properties":{"object":{"type":"string","const":"speech.timestamps"},"request_id":{"type":"string"},"status":{"type":"string","enum":["aligned","unavailable"]},"alignment_revision":{"type":"string","const":"qwen-pcm-measured-groups-v3"},"unit":{"type":"string","const":"seconds"},"granularity":{"anyOf":[{"type":"string","enum":["word","word_group"]},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":120},{"type":"null"}]},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start_time":{"type":"number","minimum":0},"end_time":{"type":"number","minimum":0}},"required":["word","start_time","end_time"],"additionalProperties":false}},"reason":{"anyOf":[{"type":"string","enum":["alignment_timeout","alignment_unavailable"]},{"type":"null"}]}},"required":["object","request_id","status","alignment_revision","unit","granularity","duration_seconds","words","reason"],"additionalProperties":false},"SpeechRequest":{"type":"object","properties":{"region":{"type":"string","enum":["cn","us"]},"id":{"type":"string"},"object":{"type":"string","const":"speech.request"},"status":{"type":"string","enum":["reserved","running","succeeded","failed","cancelled"]},"voice_id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"model_revision":{"type":"string"},"voice_version":{"type":"string"},"price_version":{"type":"string"},"usage":{"type":"object","properties":{"billable_characters":{"type":"integer","minimum":0},"trial_characters":{"type":"integer","minimum":0},"charged_usd":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."},"reserved_usd":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."},"metering_version":{"type":"string","const":"unicode-nfc-v1"}},"required":["billable_characters","trial_characters","charged_usd","reserved_usd","metering_version"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"result_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"result_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"timestamps_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["region","id","object","status","voice_id","model_revision","voice_version","price_version","usage","created_at","completed_at","result_expires_at","result_url","timestamps_url","error"],"additionalProperties":false},"Voice":{"type":"object","properties":{"region":{"type":"string","enum":["cn","us"]},"id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"object":{"type":"string","const":"voice"},"name":{"type":"string"},"status":{"type":"string","enum":["processing","ready","failed","revoked","deleting","deleted"]},"language":{"type":"string"},"voice_version":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false},{"type":"null"}]}},"required":["region","id","object","name","status","language","voice_version","created_at","updated_at","error"],"additionalProperties":false},"VoiceList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string","description":"Opaque continuation cursor. Pass it unchanged to the next request; null on the last page."},{"type":"null"}]}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"VoiceRegistration":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"language":{"type":"string","enum":["en"]},"reference_audio":{"type":"string","format":"binary","description":"Up to 4 MiB. Supported MIME types: audio/wav, audio/x-wav, audio/mpeg, audio/mp4, audio/webm, audio/ogg, audio/flac."},"reference_text":{"type":"string","maxLength":600,"description":"At most 600 Unicode code points."},"consent_type":{"type":"string","enum":["self","authorized"]},"subject_name":{"type":"string","minLength":1,"maxLength":120},"consent_confirmed":{"type":"string","const":"true"},"terms_version":{"type":"string","const":"voice-consent-v1"},"proof_reference":{"type":"string","minLength":8,"maxLength":1000,"description":"Required when consent_type=authorized. A reference to the speaker permission record, not payment or identity document data."}},"required":["name","language","reference_audio","consent_type","subject_name","consent_confirmed","terms_version"],"additionalProperties":false,"allOf":[{"if":{"properties":{"consent_type":{"const":"authorized"}}},"then":{"required":["proof_reference"]}}]},"ModelList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","const":"clone-v1"},"revision":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}},"formats":{"type":"array","items":{"type":"string","enum":["mp3","wav"]}},"max_characters":{"type":"integer","minimum":0},"daily_voice_registrations":{"type":"integer","const":5},"active_voice_limit":{"type":"integer","const":2},"streaming":{"type":"boolean"},"price":{"type":"object","properties":{"currency":{"type":"string","const":"usd"},"per_million_characters":{"type":"string","const":"12.00"},"metering":{"type":"string","const":"unicode-nfc-v1"}},"required":["currency","per_million_characters","metering"],"additionalProperties":false}},"required":["id","revision","languages","formats","max_characters","daily_voice_registrations","active_voice_limit","streaming","price"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"Wallet":{"type":"object","properties":{"workspaceId":{"type":"string"},"paidBalanceMicrousd":{"type":"string","pattern":"^-?[0-9]+$","description":"Integer micro-USD as a string; 1 USD = 1,000,000 micro-USD."},"paidReservedMicrousd":{"type":"string","pattern":"^-?[0-9]+$","description":"Integer micro-USD as a string; 1 USD = 1,000,000 micro-USD."},"availablePaidMicrousd":{"type":"string","pattern":"^-?[0-9]+$","description":"Integer micro-USD as a string; 1 USD = 1,000,000 micro-USD."},"paidDebtMicrousd":{"type":"string","pattern":"^-?[0-9]+$","description":"Integer micro-USD as a string; 1 USD = 1,000,000 micro-USD."},"trialRemainingCharacters":{"type":"integer","minimum":0},"trialReservedCharacters":{"type":"integer","minimum":0},"trialExpiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["workspaceId","paidBalanceMicrousd","paidReservedMicrousd","availablePaidMicrousd","paidDebtMicrousd","trialRemainingCharacters","trialReservedCharacters","trialExpiresAt"],"additionalProperties":false},"ProjectBalance":{"type":"object","properties":{"project_id":{"type":"string"},"monthly_budget_usd":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."},{"type":"null"}]},"charged_usd":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."},"reserved_usd":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."},"workspace_wallet_visible":{"type":"boolean","const":false}},"required":["project_id","monthly_budget_usd","charged_usd","reserved_usd","workspace_wallet_visible"],"additionalProperties":false},"Estimate":{"type":"object","properties":{"object":{"type":"string","const":"speech.estimate"},"billable_characters":{"type":"integer","minimum":0},"trial_characters":{"type":"integer","minimum":0},"estimated_charge_usd":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."},"maximum_charge_usd":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."},"currency":{"type":"string","const":"usd"},"metering_version":{"type":"string","const":"unicode-nfc-v1"},"price_version":{"type":"string"},"balance_sufficient":{"type":"boolean"},"reservation_created":{"type":"boolean","const":false},"expires_with_balance_changes":{"type":"boolean","const":true}},"required":["object","billable_characters","trial_characters","estimated_charge_usd","maximum_charge_usd","currency","metering_version","price_version","balance_sufficient","reservation_created","expires_with_balance_changes"],"additionalProperties":false},"Usage":{"type":"object","properties":{"requests":{"type":"integer","minimum":0},"characters":{"type":"integer","minimum":0},"charged_usd":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."},"by_day":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","format":"date"},"requests":{"type":"integer","minimum":0},"characters":{"type":"integer","minimum":0},"charged_usd":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","description":"USD decimal, represented as a string to preserve precision."}},"required":["day","requests","characters","charged_usd"],"additionalProperties":false}},"recent_requests":{"type":"array","items":{"$ref":"#/components/schemas/SpeechRequest"}}},"required":["requests","characters","charged_usd","by_day","recent_requests"],"additionalProperties":false},"Job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","blocked","cancel_requested","cancelled","succeeded","failed","expired"]},"voiceId":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"modelRevision":{"type":"string"},"voiceVersion":{"type":"string"},"priceVersion":{"type":"string"},"unitMicroUsd":{"type":"integer","minimum":0},"meteringVersion":{"type":"string"},"sourceCharacters":{"type":"integer","minimum":0},"billableCharacters":{"type":"integer","minimum":0},"completedCharacters":{"type":"integer","minimum":0},"chargedMicrousd":{"type":"string","pattern":"^-?[0-9]+$","description":"Integer micro-USD as a string; 1 USD = 1,000,000 micro-USD."},"trialCharacters":{"type":"integer","minimum":0},"chunkCount":{"type":"integer","minimum":0},"completedChunks":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"inputExpiresAt":{"type":"string","format":"date-time"},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"chunks":{"type":"array","items":{"type":"object","properties":{"ordinal":{"type":"integer","minimum":0},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled"]},"sourceStart":{"type":"integer","minimum":0},"sourceEnd":{"type":"integer","minimum":0},"billableCharacters":{"type":"integer","minimum":0},"requestId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chargedMicrousd":{"type":"string","pattern":"^-?[0-9]+$","description":"Integer micro-USD as a string; 1 USD = 1,000,000 micro-USD."},"trialCharacters":{"type":"integer","minimum":0},"resultExpiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ordinal","status","sourceStart","sourceEnd","billableCharacters","requestId","chargedMicrousd","trialCharacters","resultExpiresAt","errorCode"],"additionalProperties":false}}},"required":["id","status","voiceId","modelRevision","voiceVersion","priceVersion","unitMicroUsd","meteringVersion","sourceCharacters","billableCharacters","completedCharacters","chargedMicrousd","trialCharacters","chunkCount","completedChunks","createdAt","completedAt","inputExpiresAt","errorCode","chunks"],"additionalProperties":false},"RealtimeSessionInput":{"type":"object","properties":{"voice_id":{"type":"string","pattern":"^voice_[A-Za-z0-9_-]{1,100}$"},"language":{"type":"string","enum":["en"],"default":"en"},"allowed_origins":{"type":"array","maxItems":5,"items":{"type":"string","format":"uri","description":"Exact HTTPS origin. HTTP localhost/127.0.0.1 is accepted for development."},"default":[]}},"required":["voice_id"],"additionalProperties":false},"RealtimeSession":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"realtime.session"},"client_secret":{"type":"string","description":"One-use connection token. Send only in the initial session.authenticate WebSocket message. Never put tokens in URLs or permanent client storage."},"expires_at":{"type":"string","format":"date-time"},"websocket_path":{"type":"string","const":"/v1/realtime"},"format":{"type":"string","const":"pcm_s16le"},"sample_rate":{"type":"integer","const":24000},"channels":{"type":"integer","const":1},"max_session_seconds":{"type":"integer","minimum":0},"max_characters":{"type":"integer","minimum":0},"max_segment_characters":{"type":"integer","minimum":0},"protocol":{"type":"string","const":"castreader.realtime.v1"},"authentication":{"type":"string","const":"first_message"},"reconnect":{"type":"string","const":"create_new_session"}},"required":["id","object","client_secret","expires_at","websocket_path","format","sample_rate","channels","max_session_seconds","max_characters","max_segment_characters","protocol","authentication","reconnect"],"additionalProperties":false},"SpeechStreamEvent":{"oneOf":[{"type":"object","properties":{"type":{"const":"start"},"request_id":{"type":"string"},"format":{"const":"pcm_s16le"},"sample_rate":{"const":24000},"channels":{"const":1},"replayed":{"type":"boolean"},"request":{"$ref":"#/components/schemas/SpeechRequest"}},"required":["type","request_id","format","sample_rate","channels","replayed","request"],"additionalProperties":false},{"type":"object","properties":{"type":{"const":"audio"},"request_id":{"type":"string"},"seq":{"type":"integer","minimum":0},"offset_bytes":{"type":"integer","minimum":0},"audio":{"type":"string","contentEncoding":"base64","description":"Signed 16-bit little-endian mono PCM bytes."}},"required":["type","request_id","seq","offset_bytes","audio"],"additionalProperties":false},{"type":"object","properties":{"type":{"const":"done"},"request_id":{"type":"string"},"audio_bytes":{"type":"integer","minimum":0},"audio_samples":{"type":"integer","minimum":0},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"replayed":{"type":"boolean"},"request":{"$ref":"#/components/schemas/SpeechRequest"}},"required":["type","request_id","audio_bytes","audio_samples","sha256","replayed","request"],"additionalProperties":false},{"type":"object","properties":{"type":{"const":"error"},"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","retryable"],"additionalProperties":false},"request":{"$ref":"#/components/schemas/SpeechRequest"}},"required":["type","request_id","error","request"],"additionalProperties":false}]}},"responses":{"Error":{"description":"Structured API failure. HTTP 503 with code=admission_paused and retryable=true means new work is temporarily paused; use bounded backoff and retain the original idempotency key. Completed speech retries can replay retained results. HTTP 404 can indicate the whole service is disabled. A stream that already started reports an error event or terminates without a successful done event; inspect the original request before retrying.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-websocket-protocol":{"path":"/v1/realtime","protocol":"castreader.realtime.v1","transport":"Custom Node WebSocket adapter required; ordinary Next route handlers do not serve the socket.","first_message":{"type":"session.authenticate","session_id":"rts_YOUR_SESSION","token":"ONE_USE_CLIENT_SECRET"},"client_events":["text.append","text.commit","generation.cancel","ping","session.close"],"server_events":["session.ready","text.accepted","segment.accepted","start","audio","done","error","pong"],"limits":{"token_seconds":60,"max_session_seconds":120,"idle_seconds":15,"max_characters":1200,"max_segment_characters":120,"max_frame_bytes":16384,"frames_per_minute":240},"reconnect":"Create a new session; tokens are single-use."}}