Resources

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_case fields.
  • 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

v1v2
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-asyncPOST /v2/text-to-speech
GET /v1/text-to-speech-async/{operation_id}GET /v2/jobs/{id}
GET /v1/voicesGET /v2/voices (filters and pagination) and GET /v2/voices/{voice_id}
POST /v1/speech-to-textPOST /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-videoPOST /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

v1v2
Long tasksoperation_id / transcription_id, polled on a product-specific endpointOne job model for every product: GET /v2/jobs/{id}
Statusesrunning, success, failedqueued, running, succeeded, failed, canceled
TimestampsYYYY-MM-DD HH:MM:SSISO 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 filesfile URL valid for 7 daysfile_id; a signed download_url valid for 15 minutes from GET /v2/files/{id}
WebhooksUnsigned, v1 bodySigned with Voiser-Signature, event envelope { id, type, data: { job } }, retried up to 6 times
RetriesNo protection against duplicatesIdempotency-Key header
VoicesShort names such as avaOpaque ids such as voice_8f2Kq1LmZx3T
ListsFull arraysCursor pagination
Input filesPublic URLs onlyUploads 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-Key with every job-creating request.
  • Store file_ids instead of URLs; fetch a fresh download_url when needed.
  • Update error handling to read error.code (lowercase codes) and log error.request_id.
  • Parse ISO 8601 timestamps.

The full v1 reference stays available at /reference/v1.