Fish Tasks API 연동 및 사용

Fish Tasks API의 주요 기능은 Fish Audios Generation API에서 생성된 작업 ID를 입력하여 해당 작업의 실행 상태를 조회하는 것입니다. 이 문서는 Fish Tasks API의 연동 설명을 자세히 소개하여, API의 강력한 기능을 손쉽게 통합하고 충분히 활용할 수 있도록 돕습니다. Fish Tasks API를 통해 Fish Audios Generation API의 작업 실행 상태를 쉽게 조회할 수 있습니다.

신청 절차

Fish Audios Generation API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 보관해 두세요.

아직 로그인 또는 회원가입을 하지 않은 경우, 로그인 페이지로 자동 이동하여 회원가입과 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족한 경우 콘솔에서 공용 잔액을 충전할 수 있습니다.

📘 전체 문서: Fish Audios Generation API →

요청 예시

Fish Tasks API는 Fish Audios Generation API의 결과를 조회하는 데 사용할 수 있습니다. Fish Audios Generation API 사용 방법은 문서 Fish Videos Generation API 를 참고하세요. 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

curl -X POST 'https://api.acedata.cloud/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는 이 작업의 상세 정보를 반환합니다. 예를 들면 다음과 같습니다:

{
  "_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,
  "started_at": 1758440856.4,
  "finished_at": 1758440869.2,
  "elapsed": 12.8,
  "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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
      }
    ]
  }
}

반환 결과에는 여러 필드가 있으며, request 필드는 작업을 시작할 때의 request body이고, response 필드는 작업 완료 후 반환되는 response body입니다. 필드 설명은 다음과 같습니다.

id: 이 작업을 생성한 ID로, 이번 생성 작업을 고유하게 식별하는 데 사용됩니다.
request: 조회 작업의 요청 정보입니다.
response: 조회 작업의 반환 정보입니다. 최종 성공 시 그 안의 cost.amount는 이번 합성에서 실제로 차감된 Credits입니다.
created_at: 작업 생성 시간, Unix 타임스탬프(초, 부동 소수점)입니다.
started_at: 작업 실행 시작 시간, Unix 타임스탬프(초, 부동 소수점)입니다.
finished_at: 작업 완료 시간, Unix 타임스탬프(초, 부동 소수점)입니다. 작업이 완료되지 않은 경우 이 필드는 반환되지 않습니다.
elapsed: 작업 실행 소요 시간이며, 단위는 초(부동 소수점, 소수점 이하 3자리 유지)입니다. 작업이 완료되지 않은 경우 이 필드는 반환되지 않습니다.

일괄 조회 작업

이는 여러 작업 ID에 대해 작업 상세 정보를 조회하는 것으로, 위와 다른 점은 action을 retrieve_batch로 선택해야 한다는 것입니다. Request Body에는 다음이 포함됩니다:

ids: 업로드된 작업 ID 배열입니다.
action: 작업에 대한 처리 방식입니다.

설정은 아래 이미지와 같습니다:

코드 예시

페이지 오른쪽에 다양한 언어의 코드가 자동으로 생성된 것을 확인할 수 있으며, 아래 이미지와 같습니다:

일부 코드 예시는 다음과 같습니다:

응답 예시

요청이 성공하면 API는 이번의 모든 일괄 작업에 대한 구체적인 상세 정보를 반환합니다. 예를 들면 다음과 같습니다:

{
  "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,
      "started_at": 1758440856.4,
      "finished_at": 1758440869.2,
      "elapsed": 12.8,
      "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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.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,
      "started_at": 1758440856.4,
      "finished_at": 1758440869.2,
      "elapsed": 12.8,
      "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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
          }
        ]
      }
    }
  ],
  "count": 2
}

반환 결과에는 여러 필드가 있으며, 그중 items는 배치 작업의 구체적인 상세 정보가 포함되어 있고, 각 작업의 구체적인 정보는 위의 필드와 동일합니다. 필드 정보는 다음과 같습니다.

items, 배치 작업의 모든 구체적인 상세 정보입니다. 이는 배열이며, 배열의 각 요소는 위에서 단일 작업을 조회할 때의 반환 결과 형식과 동일합니다.
count, 여기서 배치 조회한 작업의 개수입니다.

CURL

curl -X POST 'https://api.acedata.cloud/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：내부 서버 오류이며, 서버에서 문제가 발생했습니다.

오류 응답 예시

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

결론

이 문서를 통해 Fish Tasks API를 사용하여 단일 또는 배치 작업의 모든 구체적인 상세 정보를 조회하는 방법을 이해하셨습니다. 이 문서가 해당 API를 더 잘 연동하고 사용하는 데 도움이 되기를 바랍니다. 궁금한 사항이 있으시면 언제든지 당사의 기술 지원팀에 문의해 주세요.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Fish Tasks API 연동 및 사용

신청 절차

요청 예시

작업 예시 이미지

요청 헤더 및 요청 본문 설정

코드 예시

CURL

응답 예시

일괄 조회 작업

코드 예시

응답 예시

CURL

오류 처리

오류 응답 예시

결론

​신청 절차

​요청 예시

​작업 예시 이미지

​요청 헤더 및 요청 본문 설정

​코드 예시

​CURL

​응답 예시

​일괄 조회 작업

​코드 예시

​응답 예시

​CURL

​오류 처리

​오류 응답 예시

​결론

신청 절차

요청 예시

작업 예시 이미지

요청 헤더 및 요청 본문 설정

코드 예시

CURL

응답 예시

일괄 조회 작업

코드 예시

응답 예시

CURL

오류 처리

오류 응답 예시

결론