> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Fish Tasks API의 연동 및 사용
> Fish music generation 集成指南 - XHuoAPI
Fish Tasks API의 주요 기능은 Fish Audios Generation API에서 생성된 작업 ID를 입력하여 해당 작업의 실행 상태를 조회하는 것입니다.
본 문서에서는 Fish Tasks API의 연동 설명을 자세히 소개하여, 귀하가 이 API의 강력한 기능을 쉽게 통합하고 충분히 활용할 수 있도록 돕겠습니다. Fish Tasks API를 통해 Fish Audios Generation API의 작업 실행 상태를 쉽게 조회할 수 있습니다.
## 신청 절차
Fish Tasks API를 사용하려면 먼저 신청 페이지 [Fish Audios Generation API](https://api.xhuoapi.ai/documents/e681b715-54fd-4464-a59a-d7f14500e095)에서 해당 서비스를 신청한 후, Fish Audios Generation API의 작업 ID를 복사해야 합니다. 아래 그림과 같이 진행합니다:
마지막으로 Tasks API 페이지 [Fish Tasks API](https://api.xhuoapi.ai/documents/44c93949-1419-4a45-8db5-8a8335de7151)에서 해당 서비스를 신청하고, 페이지에 들어가면 「Acquire」 버튼을 클릭합니다. 아래 그림과 같이 진행합니다:
로그인 또는 등록이 되어 있지 않은 경우, 자동으로 [로그인 페이지](https://api.xhuoapi.ai)로 이동하여 등록 및 로그인을 요청합니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아옵니다.
첫 신청 시 무료 사용 한도가 제공되어, 해당 API를 무료로 사용할 수 있습니다.
## 요청 예시
Fish Tasks API는 Fish Audios Generation API의 결과를 조회하는 데 사용할 수 있습니다. Fish Audios Generation API 사용 방법에 대한 자세한 내용은 문서 [Fish Videos Generation API](https://api.xhuoapi.ai/documents/fish-audios-integration)를 참조하십시오.
Fish Audios Generation API 서비스에서 반환된 작업 ID를 예로 들어, 해당 API를 사용하는 방법을 시연하겠습니다. 가정해 보겠습니다. 작업 ID가 2725a2d3-f87e-4905-9c53-9988d5a7b2f5라고 할 때, 다음과 같이 작업 ID를 전달하여 진행합니다.
### 작업 예시 그림
### 요청 헤더 및 요청 본문 설정
**Request Headers**에는 다음이 포함됩니다:
* `accept`: JSON 형식의 응답 결과를 수신하도록 지정하며, 여기서는 `application/json`으로 입력합니다.
* `authorization`: API 호출에 필요한 키로, 신청 후 직접 드롭다운에서 선택할 수 있습니다.
**Request Body**에는 다음이 포함됩니다:
* `id`: 업로드된 작업 ID.
* `action`: 작업의 조작 방식.
아래 그림과 같이 설정합니다:
### 코드 예시
페이지 오른쪽에서 다양한 언어의 코드가 자동으로 생성된 것을 확인할 수 있습니다. 아래 그림과 같이 진행합니다:
일부 코드 예시는 다음과 같습니다:
#### CURL
```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"action": "retrieve"
}'
```
### 응답 예시
요청이 성공하면 API는 해당 작업의 세부 정보를 반환합니다. 예를 들어:
```json theme={null}
{
"_id": "68cfad98550a4144a5476a92",
"id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
"application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
"created_at": 1758440856.34,
"credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
"request": {
"action": "speech",
"prompt": "a white siamese cat",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036",
"callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
},
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"type": "audios",
"user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
"response": {
"success": true,
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
]
}
}
```
반환 결과에는 여러 필드가 있으며, request 필드는 작업을 시작할 때의 request body를 나타내고, response 필드는 작업 완료 후 반환된 response body를 나타냅니다. 필드 설명은 다음과 같습니다.
* `id`: 이 작업을 생성한 ID로, 이번 생성 작업을 고유하게 식별하는 데 사용됩니다.
* `request`: 작업 조회 시의 요청 정보를 포함합니다.
* `response`: 작업 조회 시의 반환 정보를 포함합니다.
## 배치 조회 작업
이는 여러 작업 ID에 대해 작업 세부 정보를 조회하는 것으로, 위와 다른 점은 action을 retrieve\_batch로 선택해야 한다는 것입니다.
**Request Body**에는 다음이 포함됩니다:
* `ids`: 업로드된 작업 ID 배열.
* `action`: 작업의 조작 방식.
아래 그림과 같이 설정합니다:
### 코드 예시
페이지 오른쪽에서 다양한 언어의 코드가 자동으로 생성된 것을 확인할 수 있습니다. 아래 그림과 같이 진행합니다:
일부 코드 예시는 다음과 같습니다:
### 응답 예시
요청이 성공하면 API는 이번 모든 배치 작업의 구체적인 세부 정보를 반환합니다. 예를 들어:
```json theme={null}
{
"items": [
{
"_id": "68cfad98550a4144a5476a92",
"id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
"application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
"created_at": 1758440856.34,
"credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
"request": {
"action": "speech",
"prompt": "하얀 색의 샴 고양이",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036",
"callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
},
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"type": "audios",
"user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
"response": {
"success": true,
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
]
}
},
{
"_id": "68cfad98550a4144a5476a92",
"id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
"application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
"created_at": 1758440856.34,
"credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
"request": {
"action": "speech",
"prompt": "하얀 색의 샴 고양이",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036",
"callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
},
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"type": "audios",
"user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
"response": {
"success": true,
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
]
}
}
],
"count": 2
}
```
반환 결과는 여러 필드를 포함하고 있으며, items는 배치 작업의 구체적인 세부 정보가 포함되어 있습니다. 각 작업의 구체적인 정보는 위의 필드와 동일합니다.
* `items`, 배치 작업의 모든 구체적인 세부 정보. 배열이며, 각 배열의 요소는 위의 단일 작업 반환 결과 형식과 동일합니다.
* `count`, 이곳에서 배치 쿼리 작업의 개수입니다.
#### CURL
```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"ids": ["2725a2d3-f87e-4905-9c53-9988d5a7b2f5","2725a2d3-f87e-4905-9c53-9988d5a7b2f5"],
"action": "retrieve_batch"
}'
```
## 오류 처리
API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:
* `400 token_mismatched` : 잘못된 요청, 누락되었거나 잘못된 매개변수로 인한 것일 수 있습니다.
* `400 api_not_implemented` : 잘못된 요청, 누락되었거나 잘못된 매개변수로 인한 것일 수 있습니다.
* `401 invalid_token` : 인증되지 않음, 잘못되었거나 누락된 인증 토큰.
* `429 too_many_requests` : 너무 많은 요청, 비율 제한을 초과했습니다.
* `500 api_error` : 내부 서버 오류, 서버에서 문제가 발생했습니다.
### 오류 응답 예시
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "가져오기 실패"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 결론
이 문서를 통해 Fish Tasks API를 사용하여 단일 또는 배치 작업의 모든 구체적인 세부 정보를 쿼리하는 방법을 이해하셨습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.