Migrationsleitfaden
Wechseln Sie von den alten Open API-Pfaden zu Open API v1.
Migrationsleitfaden
Neue Integrationen sollten /api/open/v1 heißen. Ältere Pfade bleiben während des Kompatibilitätsfensters verfügbar, sollten jedoch nicht für neue Arbeiten verwendet werden.
Pfadzuordnung
| Legacy-Pfad | Öffnen Sie den API v1-Pfad |
|---|---|
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} |
Bestätigen Sie die endgültigen Anfrage- und Antwortformen mit:
GET /api/openapi.jsonEmpfohlene Bestellung
- Schalten Sie zuerst schreibgeschützte Anrufe um, z. B. Profil, Sprachliste und Jobstatus.
- Verschieben Sie die Erstellungsendpunkte, nachdem die Anforderungs- und Antwortanalyse durch Tests abgedeckt wurde.
- Protokollieren Sie während des Rollouts weiterhin sowohl den alten Endpunkt als auch den neuen Endpunkt.
- Entfernen Sie alte Clientpfade erst, wenn der Produktionsverkehr nicht mehr von ihnen abhängt.
Änderungen anfordern
Verwenden Sie die Inhaberauthentifizierung für jede v1-Anfrage.
Authorization: Bearer FISHAUDIO_API_KEYBevorzugen Sie stabile IDs in Anforderungstexten. Senden Sie für TTS die Sprach-ID in voiceId und die TTS-Engine-Modell-ID in modelId. Nur reference_id bleibt ein veralteter Alias für die Sprach-ID.
Verwenden Sie die öffentliche Systemstimme 00a1b221-6137-4b73-ad62-b0cbce134167 für einen kleinen Migrationsrauchtest und wechseln Sie dann zur von Ihrer Anwendung ausgewählten Produktions-Sprach-ID.
Antwortänderungen
V1-Endpunkte basieren auf expliziten Ressourcen: Stimmen, Aufgaben, Jobs und Profildatensätze. Aktualisieren Sie Ihren Client, um endpunktspezifische Antwortfelder zu analysieren, anstatt von einer globalen Wrapper-Form abhängig zu sein.
Behalten Sie bei asynchronen Medienvorgängen die zurückgegebene Job- oder Aufgaben-ID sofort bei. Für Umfragen, Wiederholungsversuche und Supportuntersuchungen sollte diese ID verwendet werden.
Abrechnung und Gutschriften
Durch die Migration selbst ändert sich der Kontostand nicht, aber neue Endpunkte können klarere Guthaben- und Kontingentfelder verfügbar machen. Vergleichen Sie während der Einführung alte und neue Codepfade bei kleinen Aufträgen, bevor Sie großen Datenverkehr verschieben.
Wenn eine Anfrage während der Migration fehlschlägt, protokollieren Sie den alten Pfad, den neuen Pfad, den Statuscode, API requestId und Ihre interne Job-ID. Dadurch erhält der Support ausreichend Kontext, ohne dass Inhaber-API-Schlüssel oder private Medien-URLs offengelegt werden.