마이그레이션 가이드
레거시 Open API 경로에서 Open API v1로 이동합니다.
마이그레이션 가이드
새로운 통합에서는 /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을 노출하지 않고도 충분한 컨텍스트를 지원합니다.