비동기 작업 v1
비동기 TTS 작업을 생성하고 폴링합니다.
비동기 작업
오디오가 처리되는 동안 사용자가 페이지를 떠날 수 있는 긴 텍스트, 일괄 생성, 웹훅 스타일 워크플로 및 UI 흐름에 비동기 TTS 작업을 사용하세요.
작업 생성
POST /api/open/v1/speech/tts/jobs
Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json요구
{
"text": "Hello from Fish Audio.",
"voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
"modelId": "fishaudio-s21pro-flash",
"format": "mp3",
"speed": 1,
"volume": 0,
"stability": 1,
"similarity": 1,
"pitch": 0,
"language": "auto",
"emotion": "neutral",
"instruction": "Speak naturally",
"textNormalization": true
}텍스트 해시, 요청한 음성 및 반환된 작업 ID를 데이터베이스에 유지합니다. 작업자 생성 후 충돌이 발생하는 경우 작업 ID로 폴링하는 것이 두 번째 작업을 생성하는 것보다 안전합니다.
이 예에서는 공개 시스템 테스트 음성 00a1b221-6137-4b73-ad62-b0cbce134167를 사용합니다. 연결을 확인한 후 원하는 Voice ID로 교체하세요.
curl https://fishaudio.org/api/open/v1/speech/tts/jobs \
-H "Authorization: Bearer FISHAUDIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Hello from Fish Audio.","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}'응답
생성 엔드포인트는 202 Accepted를 반환합니다. 폴링을 시작하기 전에 task.id를 저장하세요.
{
"task": {
"id": "task_123",
"status": "pending",
"audioUrl": null,
"delivery": { "downloadUrl": null, "downloadReady": false }
},
"record": { "id": "task_123", "status": "pending" },
"requestId": "req_123",
"quotaRemaining": 99994,
"creditsUsed": 6
}취업
GET /api/open/v1/speech/tts/jobs/{taskId}
Authorization: Bearer FISHAUDIO_API_KEY상태 값은 pending, processing, success, partial_fail, fail입니다.
GET /api/open/tts/jobs/{taskId}/audio?download=1
Authorization: Bearer FISHAUDIO_API_KEYtask.segments[].playbackUrl에도 같은 헤더가 필요합니다. 다운로드 복구를 위해 새 작업을 만들지 마세요.
분실한 작업 ID 복구
생성 요청이 서버에 도달했지만 클라이언트가 202 Accepted 응답을 받지 못했다면 먼저 최근 작업을 조회하세요.
curl "https://fishaudio.org/api/open/v1/speech/tts/jobs?limit=20&createdAfter=2026-07-20T00%3A00%3A00Z" \
-H "Authorization: Bearer FISHAUDIO_API_KEY"결과는 생성 시간의 최신순으로 정렬됩니다. createdAt, textFingerprint, voiceId, engineModelId로 로컬 요청과 일치하는 작업을 찾을 수 있습니다. page, limit(최대 100), status, ISO 8601 형식의 createdAfter를 지원합니다. 목록에는 텍스트 미리보기만 포함되며 전체 텍스트는 반환되지 않습니다. taskId를 찾은 뒤 기존 작업을 계속 폴링하세요. 목록 조회는 API 할당량을 소비하지 않습니다.
청구 및 크레딧
서버는 작업을 수락할 때 creditsUsed를 한 번만 예약합니다. 폴링, 다운로드 및 동일한 오디오의 반복 다운로드에는 추가 요금이 없습니다. 선결제된 작업이 실패하면 멱등 환불 경로를 통해 크레딧이 반환됩니다.
일괄 처리의 경우 많은 수의 작업을 추가하기 전에 동시성을 조절하고 프로필을 확인하세요. 크레딧 부족으로 인해 하나의 작업이 실패하면 계정 소유자가 잔액을 해결할 때까지 배치의 rest를 일시 중지합니다.
오류
| 상태 | 의미 | 액션 |
|---|---|---|
400 | 잘못된 텍스트, 음성, 모델 또는 출력 형식 | 페이로드 수정 |
401 | 인증 실패 | 폴링 중지 및 자격 증명 새로 고침 |
402 | 부족한 크레딧 또는 할당량 | 대기열 일시 중지 |
404 | 이 API 키에 대해 작업 ID를 알 수 없습니다. | 동일한 계정에 대해 반환된 ID를 저장했는지 확인 |
429 | 만들기 또는 폴링 요청이 너무 많습니다 | 물러서서 작업 ID 유지 |