Core concepts
Idempotency
Retry job-creating requests safely, without creating or paying for duplicates.
Networks fail. If a request times out you cannot know whether Voiser received it. Add an Idempotency-Key header to requests that create jobs, and you can retry them as often as you need: the first request creates the job, and every retry with the same key returns that same job instead of starting (and charging for) a new one.
curl -X POST https://api.34.181.188.80.sslip.io/v2/text-to-speech \
-H "Authorization: Bearer $VOISER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-intro-audio" \
-d '{ "text": "Thanks for your order!", "voice_id": "voice_8f2Kq1LmZx3T" }'Choosing a key
- 8 to 100 characters from
A-Z,a-z,0-9and_ . : -. - Use one key per logical operation. A random UUID generated when you first decide to do the work is ideal; an id from your own system (such as
order-1042-intro-audio) works well too. - Reuse the key only to retry the same request. Sending a different body with a key you already used fails with
409 job_idempotency_conflict.
Behaviour
| Situation | Result |
|---|---|
| First request with a key | The job is created; 202 with the new job. |
| Retry with the same key and the same body | No new job; the original job is returned in its current state. |
| Same key, different body | 409 with job_idempotency_conflict. |
| No key | Every request creates a new job. |
Read requests (GET) are always safe to retry and do not need a key.
Endpoints that accept a key
POST
/v2/filesCreate an uploadPOST/v2/files/importImport a file from a URLPOST/v2/text-to-speechConvert text to speechPOST/v2/tts-projectsCreate a projectPOST/v2/tts-projects/importCreate a project from a document or web pagePOST/v2/tts-projects/{project_id}/exportExport a project to audioPOST/v2/transcriptionsTranscribe audio or videoPOST/v2/transcriptions/{transcription_id}/translateTranslate a transcriptionPOST/v2/transcriptions/{transcription_id}/summarySummarize a transcriptionPOST/v2/transcriptions/{transcription_id}/action-itemsExtract action itemsPOST/v2/transcriptions/{transcription_id}/chaptersSplit a transcription into chaptersPOST/v2/transcriptions/{transcription_id}/askAsk a question about a transcriptionPOST/v2/dubbingDub a video or audio filePOST/v2/dubbing/{dubbing_id}/languagesAdd a target languagePOST/v2/voice-clones/consent-sentenceGet a consent sentencePOST/v2/voice-clonesCreate a voice clonePOST/v2/voice-clones/{voice_clone_id}/speechSpeak short text with a voice clonePOST/v2/musicGenerate a songPOST/v2/music/lyricsWrite or rework song lyricsPOST/v2/videosGenerate a videoPOST/v2/videos/{video_id}/extendExtend a videoPOST/v2/videos/enhance-promptImprove a video prompt