Migration Guide

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.

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.

HTTP v2 sync to v3

POST /api/open/v2/speech/tts remains available, and no retirement date has been set. Migrate each client as follows:

1. Change the endpoint to POST /api/open/v3/speech/tts and continue sending the API key in Authorization: Bearer. Remove any token field from the request body.
2. Keep text, voiceId, and supported generic controls. Read GET /api/open/v3/speech/tts/capabilities, then verify that the selected voice lists the chosen public model in modelIds. Put that model ID in modelId; do not carry over v2 engineModelId, version, or qwenModel fields.
3. If the v2 client sends minimaxEmotion, check that the target model supports emotion control before mapping it to v3 emotion. Remove other provider-specific fields. V3 rejects unknown fields with 400.
4. Use a stable Idempotency-Key for each logical generation and keep X-Request-Id for tracing. Verify audio, errors, and quota with representative requests before switching production traffic.
5. For long text or recoverable results, use POST /api/open/v3/speech/tts/jobs, store the task ID, and poll and download the result. Completed synchronous v3 responses cannot be replayed.

This section concerns HTTP synchronous v2 only. /v2/tts/live is a separate Realtime protocol.

Path Mapping

Confirm final request and response shapes with:

GET /api/openapi.json

Recommended Order

1. Switch read-only calls first, such as profile, voice list, and job status.
2. Move creation endpoints after request and response parsing is covered by tests.
3. Keep logging both the legacy endpoint and new endpoint during rollout.
4. 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_KEY

Prefer 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.