Migration Guide
Move from legacy Open API paths to Open API v1.
Migration Guide
New integrations should call /api/open/v1. Legacy paths remain available 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 YOUR_API_TOKENPrefer stable ids in request bodies. For TTS, new code should send voiceId; older aliases such as modelId or reference_id should remain only in compatibility adapters.
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 tokens or private media URLs.