Guia de migração
Mude dos caminhos legados do Open API para o Open API v1.
Guia de migração
Migração de TTS para v3
Novos clientes devem usar HTTP v3 e Realtime v3; HTTP v1/v2 e Realtime v2 continuam compatíveis. Em HTTP, use /api/open/v3/speech/tts, /api/open/v3/speech/tts/jobs, /api/open/v3/voices e /api/open/v3/openapi.json, enviando o voiceId da plataforma, o modelId público e controles genéricos. Realtime usa /v3/tts/live, realtime.tts.msgpack.v3, camelCase e ready.effectiveRequest.
Com exceção dos endpoints TTS descritos acima, novas integrações de superfícies Open API que ainda não oferecem v3 devem usar /api/open/v1. Os caminhos legados permanecem apenas para compatibilidade com clientes existentes e não devem ser usados em novos desenvolvimentos.
Mapeamento de caminho
| Caminho legado | Abra o caminho API v1 |
|---|---|
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} |
Confirme a solicitação final e os formatos de resposta com:
GET /api/openapi.jsonPedido recomendado
- Alterne primeiro as chamadas somente leitura, como perfil, lista de voz e status do trabalho.
- Mova os endpoints de criação depois que a análise de solicitação e resposta for coberta pelos testes.
- Continue registrando o endpoint legado e o novo endpoint durante a implementação.
- Remova os caminhos de clientes legados somente depois que o tráfego de produção não depender mais deles.
Solicitar alterações
Use autenticação de portador para cada solicitação v1.
Authorization: Bearer FISHAUDIO_API_KEYPrefira IDs estáveis nos corpos das solicitações. Para TTS, envie o ID de voz em voiceId e o ID do modelo do mecanismo TTS em modelId. Apenas reference_id permanece como alias legado do ID de voz.
Use a voz do sistema público 00a1b221-6137-4b73-ad62-b0cbce134167 para um pequeno teste de fumaça de migração e, em seguida, mude para o ID de voz de produção selecionado pelo seu aplicativo.
Mudanças de resposta
Os endpoints V1 são projetados em torno de recursos explícitos: vozes, tarefas, trabalhos e registros de perfil. Atualize seu cliente para analisar campos de resposta específicos do endpoint em vez de depender de um formato de wrapper global.
Para operações de mídia assíncronas, persista imediatamente o trabalho retornado ou a ID da tarefa. Pesquisas, novas tentativas e investigações de suporte devem usar esse ID.
Faturamento e créditos
A migração em si não altera o saldo da conta, mas novos terminais podem expor créditos e campos de cota mais claros. Durante a implementação, compare caminhos de código novos e antigos em tarefas pequenas antes de mover tráfego de alto volume.
Se uma solicitação falhar durante a migração, registre o caminho herdado, o novo caminho, o código de status, API requestId e seu ID de trabalho interno. Isso fornece contexto suficiente sem expor chaves API do portador ou URLs de mídia privada.