Migration Guide
Move from legacy Open API paths to Open API v1.
Migration Guide
TTS v3 migration
New TTS clients should use HTTP v3 and Realtime v3. Existing HTTP v1/v2 and Realtime v2 clients remain compatible.
| Existing contract | Recommended v3 contract |
|---|---|
POST /api/open/v1/speech/tts | POST /api/open/v3/speech/tts |
POST /api/open/v1/speech/tts/jobs | POST /api/open/v3/speech/tts/jobs |
GET /api/open/v1/voices | GET /api/open/v3/voices |
GET /api/openapi.json | GET /api/open/v3/openapi.json |
/v2/tts/live + realtime.tts.msgpack.v2 | /v3/tts/live + realtime.tts.msgpack.v3 |
For HTTP, send only text, platform voiceId, public modelId, and generic controls. For Realtime, change snake_case fields to camelCase, place synthesis controls under start.request, and use ready.effectiveRequest as the effective configuration. Preserve X-Request-Id for HTTP retries and requestId for reliable Realtime recovery.
Except for the TTS endpoints described above, new integrations for Open API surfaces that do not yet offer v3 should call /api/open/v1. Legacy paths remain available for existing clients during the compatibility window, but they should not be used for new work.
Path Mapping
| Legacy Path | Open API v1 Path |
|---|---|
POST /api/open/create-model | POST /api/open/v1/voices |
POST /api/open/delete-model | DELETE /api/open/v1/voices/{voiceId} |
POST /api/open/list-models | GET /api/open/v1/voices |
POST /api/open/lip-sync/create | POST /api/open/v1/media/lip-sync/jobs |
GET /api/open/lip-sync/list | GET /api/open/v1/media/lip-sync/jobs |
GET /api/open/lip-sync/query | GET /api/open/v1/media/lip-sync/jobs/{jobId} |
Confirm final request and response shapes with:
GET /api/openapi.jsonRecommended Order
- Switch read-only calls first, such as profile, voice list, and job status.
- Move creation endpoints after request and response parsing is covered by tests.
- Keep logging both the legacy endpoint and new endpoint during rollout.
- Remove legacy client paths only after production traffic no longer depends on them.
Request Changes
Use bearer authentication for every v1 request.
Authorization: Bearer FISHAUDIO_API_KEYPrefer stable ids in request bodies. For TTS, send the voice id in voiceId and the TTS engine model id in modelId. Only reference_id remains a legacy voice-id alias.
Use the public system voice 00a1b221-6137-4b73-ad62-b0cbce134167 for a small migration smoke test, then switch to the production Voice ID selected by your application.
Response Changes
V1 endpoints are designed around explicit resources: voices, tasks, jobs, and profile records. Update your client to parse endpoint-specific response fields instead of depending on one global wrapper shape.
For async media operations, persist the returned job or task id immediately. Polling, retries, and support investigations should use that id.
Billing And Credits
Migration itself does not change account balance, but new endpoints may expose clearer credits and quota fields. During rollout, compare old and new code paths on small jobs before moving high-volume traffic.
If a request fails during migration, log the legacy path, new path, status code, API requestId, and your internal job id. That gives support enough context without exposing bearer API keys or private media URLs.