Migrating from v1
Move an integration of the previous voiser.ai API to v2, endpoint by endpoint.
v1 is the API of the previous voiser.ai platform. It keeps working unchanged, so nothing breaks on migration day. v2 is where new features land: more voices and products, jobs with progress, signed webhooks, idempotency and consistent errors. Because the same API key works for both versions, you can move one endpoint at a time.
What stays the same
- Your API key. Existing voiser.ai keys are valid for v1 and v2.
- Authentication.
Authorization: Bearer <key>. - JSON with
snake_casefields. - Credits. Both versions draw from the same balance as the studio. See Credits.
- Rate limits. 60 write and 300 read requests per minute per key in both versions.
Endpoint mapping
| v1 | v2 |
|---|---|
POST /v1/text-to-speech (waits for the audio, up to 7,000 characters) | POST /v2/text-to-speech (returns a job, up to 100,000 characters), then GET /v2/jobs/{id} or a webhook |
POST /v1/text-to-speech-async | POST /v2/text-to-speech |
GET /v1/text-to-speech-async/{operation_id} | GET /v2/jobs/{id} |
GET /v1/voices | GET /v2/voices (filters and pagination) and GET /v2/voices/{voice_id} |
POST /v1/speech-to-text | POST /v2/transcriptions (coming soon) |
GET /v1/speech-to-text/{transcription_id} | GET /v2/transcriptions/{id} (coming soon) |
POST /v1/text-to-video, POST /v1/image-to-video | POST /v2/videos (coming soon) |
GET /v1/video-result/{operation_id} | GET /v2/jobs/{id} |
Until the v2 transcription and video endpoints are released, keep using v1 for those.
What changes
| v1 | v2 | |
|---|---|---|
| Long tasks | operation_id / transcription_id, polled on a product-specific endpoint | One job model for every product: GET /v2/jobs/{id} |
| Statuses | running, success, failed | queued, running, succeeded, failed, canceled |
| Timestamps | YYYY-MM-DD HH:MM:SS | ISO 8601 in UTC (2026-11-17T10:24:31.000Z) |
| Errors | { "error": true, "detail": [{ "code": "API_KEY_INVALID", … }] } | { "error": { "code": "auth_api_key_invalid", "message", "details", "request_id" } }. See Errors |
| Result files | file URL valid for 7 days | file_id; a signed download_url valid for 15 minutes from GET /v2/files/{id} |
| Webhooks | Unsigned, v1 body | Signed with Voiser-Signature, event envelope { id, type, data: { job } }, retried up to 6 times |
| Retries | No protection against duplicates | Idempotency-Key header |
| Voices | Short names such as ava | Opaque ids such as voice_8f2Kq1LmZx3T |
| Lists | Full arrays | Cursor pagination |
| Input files | Public URLs only | Uploads or imports, then file_id |
Step by step: text to speech
v1
curl -X POST https://api.34.181.188.80.sslip.io/v1/text-to-speech \
-H "Authorization: Bearer $VOISER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "text": "Hello!", "voice_id": "ava", "speed": 1 }'
# → { "file": "https://…/audio.mp3", "file_duration": 1.2 }v2
# 1. Find the new voice id (once)
curl "https://api.34.181.188.80.sslip.io/v2/voices?search=ava&include_legacy=true" \
-H "Authorization: Bearer $VOISER_API_KEY"
# 2. Start the job
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: hello-0001" \
-d '{ "text": "Hello!", "voice_id": "voice_8f2Kq1LmZx3T", "settings": { "speed": 1 } }'
# 3. Wait for the job (or use webhook_url), then download result.file_id
curl https://api.34.181.188.80.sslip.io/v2/jobs/<job id> -H "Authorization: Bearer $VOISER_API_KEY"
curl https://api.34.181.188.80.sslip.io/v2/files/<file id> -H "Authorization: Bearer $VOISER_API_KEY"Voice parameters move into settings (speed, pitch, emotion, instructions and more). v1 style corresponds to settings.emotion, and v1 instruction to settings.instructions. Voices of the previous platform are listed with include_legacy=true.
Checklist
- Map each v1 voice id you use to a v2
voice_…id and store it. - Replace product-specific polling with
GET /v2/jobs/{id}, or add a webhook endpoint that verifies signatures. - Send an
Idempotency-Keywith every job-creating request. - Store
file_ids instead of URLs; fetch a freshdownload_urlwhen needed. - Update error handling to read
error.code(lowercase codes) and logerror.request_id. - Parse ISO 8601 timestamps.
The full v1 reference stays available at /reference/v1.