{"openapi":"3.1.0","info":{"title":"Phumi TTS API","version":"3.0.0"},"servers":[{"url":"/tts"}],"security":[{"PhumiAPIKey":[]}],"components":{"securitySchemes":{"PhumiAPIKey":{"type":"http","scheme":"bearer","description":"Create a phumi_sk_… key in Studio → API keys."}}},"paths":{"/v1/reels":{"get":{"summary":"Reel price, paid eligibility and your active job (feature flag required)","responses":{"200":{"description":"Reel settings"},"401":{"description":"Invalid API key or session"},"404":{"description":"Feature disabled"}}},"post":{"summary":"Reserve credits and queue a Khmer Reel of up to 20 seconds","parameters":[{"in":"header","name":"Idempotency-Key","schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["topic","voice_id"],"properties":{"topic":{"type":"string","minLength":1,"maxLength":500},"voice_id":{"type":"string","enum":["warm_narrator","deep_narrator","bright_storyteller","vichea","sophea","rithy","chantha","malis","piseth"]},"request_id":{"type":"string","format":"uuid"}}}}}},"responses":{"202":{"description":"Queued; returns job_id"},"401":{"description":"Invalid API key or session"},"402":{"description":"Not enough credits"},"403":{"description":"Paid purchase required; Khmer detail and upgrade_url"},"404":{"description":"Feature disabled"},"409":{"description":"One active Reel per user or request ID reused with different input"},"422":{"description":"Invalid input"},"429":{"description":"Queue full; retry later"},"503":{"description":"Processing unavailable"}}}},"/v1/reels/{job_id}":{"get":{"summary":"Your Reel status, timings and an expiring private MP4 download URL","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"responses":{"200":{"description":"queued | scripting | voicing | rendering | done | failed; download_url is available when done"},"401":{"description":"Invalid API key or session"},"404":{"description":"Job not found or feature disabled"}}}},"/v1/usage":{"get":{"summary":"Current credit balance","responses":{"200":{"description":"Usage"},"401":{"description":"Invalid API key or session"}}}},"/v1/voices":{"get":{"summary":"Built-in and your private voices","description":"Lists enabled default voices and your private voices. A disabled default voice is rejected for new generation requests; existing jobs can still be retrieved.","responses":{"200":{"description":"Voices"},"401":{"description":"Invalid API key or session"}}}},"/v1/tts":{"post":{"summary":"Generate and save one clip","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":50000,"description":"Free accounts: up to 1,000 Unicode characters per generation. Paid accounts: up to 50,000. Leading and trailing whitespace is trimmed."},"voice_id":{"type":"string","default":"warm_narrator"},"speed":{"type":"number","enum":[0.75,1,1.25,1.5],"default":1},"cfg_value":{"type":"number","minimum":0.1,"maximum":10,"default":2},"inference_timesteps":{"type":"integer","minimum":1,"maximum":30,"default":10},"replacement":{"type":"object","additionalProperties":false,"required":["job_id","index"],"description":"Replace one subtitle of an owned completed timed job. Send the full updated text/subtitles with the same voice and timestamps; all other lines must match. Only the selected line is charged. Success saves a new complete recording; failure retains the source and refunds the replacement reservation. Source recordings up to 64 MiB are supported. Reuse request_id after a lost response.","properties":{"job_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$"},"index":{"type":"integer","minimum":0,"maximum":999,"description":"Zero-based subtitle index."}}},"subtitles":{"type":"array","minItems":1,"maxItems":1000,"description":"Optional timed subtitles. Text must equal the trimmed cue texts joined with a newline; speed must be 1. Timestamps are milliseconds, ordered, non-overlapping and within one hour. Speech starts at each start_ms; silence fills the remaining slot. Overflow fails the whole recording and refunds credits; speech is never clipped or accelerated.","items":{"type":"object","additionalProperties":false,"required":["start_ms","end_ms","text"],"properties":{"start_ms":{"type":"integer","minimum":0,"maximum":3600000},"end_ms":{"type":"integer","minimum":1,"maximum":3600000},"text":{"type":"string","minLength":1,"maxLength":50000}}}}}}}}},"responses":{"200":{"description":"Generated WAV","content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Invalid API key or session"},"402":{"description":"Not enough credits"},"422":{"description":"Invalid input"},"429":{"description":"Queue full; retry later"},"503":{"description":"Processing unavailable"}}}},"/v1/tts/jobs":{"get":{"summary":"Your recent generation jobs","responses":{"200":{"description":"Jobs"},"401":{"description":"Invalid API key or session"}}},"post":{"summary":"Queue a clip; reuse request_id to recover the same job","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","request_id"],"properties":{"text":{"type":"string","minLength":1,"maxLength":50000,"description":"Free accounts: up to 1,000 Unicode characters per generation. Paid accounts: up to 50,000. Leading and trailing whitespace is trimmed."},"voice_id":{"type":"string","default":"warm_narrator"},"speed":{"type":"number","enum":[0.75,1,1.25,1.5],"default":1},"cfg_value":{"type":"number","minimum":0.1,"maximum":10,"default":2},"inference_timesteps":{"type":"integer","minimum":1,"maximum":30,"default":10},"replacement":{"type":"object","additionalProperties":false,"required":["job_id","index"],"description":"Replace one subtitle of an owned completed timed job. Send the full updated text/subtitles with the same voice and timestamps; all other lines must match. Only the selected line is charged. Success saves a new complete recording; failure retains the source and refunds the replacement reservation. Source recordings up to 64 MiB are supported. Reuse request_id after a lost response.","properties":{"job_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$"},"index":{"type":"integer","minimum":0,"maximum":999,"description":"Zero-based subtitle index."}}},"subtitles":{"type":"array","minItems":1,"maxItems":1000,"description":"Optional timed subtitles. Text must equal the trimmed cue texts joined with a newline; speed must be 1. Timestamps are milliseconds, ordered, non-overlapping and within one hour. Speech starts at each start_ms; silence fills the remaining slot. Overflow fails the whole recording and refunds credits; speech is never clipped or accelerated.","items":{"type":"object","additionalProperties":false,"required":["start_ms","end_ms","text"],"properties":{"start_ms":{"type":"integer","minimum":0,"maximum":3600000},"end_ms":{"type":"integer","minimum":1,"maximum":3600000},"text":{"type":"string","minLength":1,"maxLength":50000}}}},"request_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Existing job"},"202":{"description":"Accepted job"},"401":{"description":"Invalid API key or session"},"402":{"description":"Not enough credits"},"409":{"description":"Request ID already used for different input"},"422":{"description":"Invalid input"},"429":{"description":"Queue full; retry later"},"503":{"description":"Processing unavailable"}}}},"/v1/tts/jobs/{job_id}":{"get":{"summary":"Your job status","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job"},"401":{"description":"Invalid API key or session"},"404":{"description":"Job not found"}}}},"/v1/tts/jobs/{job_id}/audio":{"get":{"summary":"Your completed job's WAV","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"WAV","content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Invalid API key or session"},"404":{"description":"Job not found"},"409":{"description":"Audio is not yet available"}}}}}}