마이그레이션 가이드
레거시 Open API 경로에서 Open API v1로 이동합니다.
마이그레이션 가이드
TTS v3 마이그레이션
새 클라이언트는 HTTP v3와 Realtime v3를 사용하세요. HTTP v1/v2와 Realtime v2는 계속 호환됩니다. HTTP는 /api/open/v3/speech/tts, /api/open/v3/speech/tts/jobs, /api/open/v3/voices, /api/open/v3/openapi.json을 사용하고 플랫폼 voiceId, 공개 modelId, 공통 제어만 전송합니다. Realtime은 /v3/tts/live, realtime.tts.msgpack.v3, camelCase, ready.effectiveRequest를 사용합니다.
위에서 설명한 TTS 엔드포인트를 제외하고 아직 v3를 제공하지 않는 Open API 기능의 새 연동은 /api/open/v1를 사용해야 합니다. 기존 경로는 기존 클라이언트 호환용으로만 유지되며 새 개발에는 사용하지 마세요.
경로 매핑
| 레거시 경로 | 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} |
다음을 통해 최종 요청 및 응답 형태를 확인합니다.
GET /api/openapi.json추천주문
- 프로필, 음성 목록, 작업 상태 등 읽기 전용 통화를 먼저 전환합니다.
- 요청 및 응답 구문 분석이 테스트에 포함된 후 생성 끝점을 이동합니다.
- 롤아웃 중에 레거시 엔드포인트와 새 엔드포인트를 모두 계속해서 기록합니다.
- 프로덕션 트래픽이 더 이상 의존하지 않는 후에만 레거시 클라이언트 경로를 제거하십시오.
변경 요청
모든 v1 요청에 대해 베어러 인증을 사용합니다.
Authorization: Bearer FISHAUDIO_API_KEY요청 본문에서는 안정적인 ID를 사용하세요. TTS에서는 음성 ID를 voiceId로, TTS 엔진 모델 ID를 modelId로 전송합니다. reference_id만 음성 ID의 레거시 별칭으로 남습니다.
소규모 마이그레이션 스모크 테스트를 위해 공개 시스템 음성 00a1b221-6137-4b73-ad62-b0cbce134167를 사용한 다음 애플리케이션에서 선택한 프로덕션 Voice ID로 전환하세요.
응답 변경
V1 엔드포인트는 음성, 작업, 작업 및 프로필 기록과 같은 명시적인 리소스를 중심으로 설계되었습니다. 하나의 전역 래퍼 형태에 의존하는 대신 엔드포인트별 응답 필드를 구문 분석하도록 클라이언트를 업데이트하세요.
비동기 미디어 작업의 경우 반환된 작업 또는 작업 ID를 즉시 유지합니다. 폴링, 재시도 및 지원 조사에서는 해당 ID를 사용해야 합니다.
청구 및 크레딧
마이그레이션 자체는 계정 잔액을 변경하지 않지만 새 엔드포인트는 더 명확한 크레딧 및 할당량 필드를 노출할 수 있습니다. 롤아웃 중에 대용량 트래픽을 이동하기 전에 소규모 작업의 이전 코드 경로와 새 코드 경로를 비교하십시오.
마이그레이션 중에 요청이 실패하면 기존 경로, 새 경로, 상태 코드, API requestId 및 내부 작업 ID를 기록합니다. 이는 전달자 API 키나 개인 미디어 URL을 노출하지 않고도 충분한 컨텍스트를 지원합니다.