> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 자주 묻는 질문

> Supertone API에 관한 자주 묻는 질문 — API Key, 보이스, 크레딧, 오류, 연동 방법을 다룹니다.

<Note>
  이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/resources/faq)을 함께 확인해 주세요.
</Note>

## API 시작하기

<Accordion title="API Key는 어디서 발급받나요?">
  [개발자 콘솔](https://console.supertoneapi.com)에 가입하고 새 키를 생성하세요. 계정당 최대 **3개의 키**를 발급할 수 있으며, 언제든지 폐기하거나 재발급할 수 있습니다.
</Accordion>

<Accordion title="요청은 어떻게 인증하나요?">
  모든 요청에 `x-sup-api-key: [YOUR_API_KEY]` 헤더를 포함하세요. 두 SDK 모두 생성자를 통해 키를 받습니다 — [인증](/ko/docs/authentication)을 참고해 주세요.
</Accordion>

<Accordion title="Play 계정과 별도로 가입해야 하나요?">
  아니요. API와 [Supertone Play](https://play.supertone.ai)는 동일한 계정, 크레딧 잔액, 보이스 라이브러리를 공유합니다.
</Accordion>

<Accordion title="공식적으로 지원되는 SDK는 무엇인가요?">
  두 SDK가 공식 지원됩니다. [Python](/ko/docs/developer-tools/python)(PyPI의 `supertone`)과 [TypeScript](/ko/docs/developer-tools/typescript)(npm의 `@supertone/supertone`)입니다. 다른 언어에서는 [REST API](/ko/api-reference/introduction)를 직접 호출하시기 바랍니다.
</Accordion>

## 보이스와 TTS 호출

<Accordion title="보이스 ID는 어떻게 찾나요?">
  세 가지 방법이 있습니다. (1) [Supertone Play](https://play.supertone.ai)의 보이스 카드에서 복사, (2) `GET /v1/voices` 호출, (3) `GET /v1/voices/search`로 필터 검색. 자세한 내용은 [보이스](/ko/docs/core-concepts/voices)를 참고해 주세요.
</Accordion>

<Accordion title="Play에서 만든 클론드 보이스를 API에서 사용할 수 있나요?">
  네. Play에서 클로닝한 보이스는 동일 계정의 API에서 즉시 사용할 수 있습니다. 마찬가지로 `POST /v1/custom-voices/cloned-voice`를 통해 생성한 보이스도 Play에서 바로 확인할 수 있습니다. 별도의 동기화 과정은 필요하지 않습니다.
</Accordion>

<Accordion title="존재하는 보이스인데도 403이 발생합니다. 왜 그런가요?">
  커스텀(클론드) 보이스는 해당 보이스를 생성한 계정에서만 호출할 수 있습니다. 다른 계정의 키를 사용하면 API는 `403 Forbidden`을 반환합니다.
</Accordion>

<Accordion title="보이스가 지원하는 언어/스타일/모델 조합은 어디서 확인하나요?">
  보이스 객체의 `samples` 필드에 지원되는 모든 `(language, style, model)` 조합과 각 조합의 미리듣기 URL이 포함되어 있습니다. TTS 요청을 보내기 전에 확인하세요.
</Accordion>

<Accordion title="style은 필수 입력인가요?">
  아니요. `style`을 생략하면 해당 보이스의 `styles` 배열의 첫 번째 값이 기본값으로 사용됩니다.
</Accordion>

<Accordion title="피치나 속도를 조정할 수 있나요?">
  네 — [Voice settings](/ko/docs/text-to-speech/voice-settings)를 참고해 주세요. 모델마다 지원하는 파라미터가 다르며, 지원되지 않는 설정은 조용히 무시됩니다.
</Accordion>

<Accordion title="텍스트는 얼마나 길게 입력할 수 있나요?">
  raw API는 `text`를 **300자**로 제한합니다. Python과 TypeScript SDK는 더 긴 텍스트를 자동으로 청크 분할한 뒤 오디오를 병합합니다. 자세한 내용은 [장문 처리](/ko/docs/text-to-speech/long-text)를 참고해 주세요.
</Accordion>

<Accordion title="`predict_duration`은 어떤 용도인가요?">
  주어진 텍스트의 생성 오디오 예상 길이를 반환합니다 — **크레딧이 차감되지 않습니다**. 비용 미리보기와 UI 힌트에 유용합니다. [Predict duration](/ko/docs/production/cost-and-usage#predict-duration)을 참고해 주세요.
</Accordion>

## 크레딧과 요금제

<Accordion title="API는 어떻게 과금되나요?">
  생성된 오디오의 초 단위로 크레딧이 차감됩니다. Play와 동일한 크레딧 시스템을 사용하며, [Play 구독 페이지](https://play.supertone.ai/subscription)에서 크레딧을 구매할 수 있습니다.
</Accordion>

<Accordion title="크레딧 잔액은 어떻게 확인하나요?">
  두 가지 방법이 있습니다. (1) `GET /v1/credits`를 호출(또는 SDK의 `get_credit_balance` 사용), (2) 콘솔 또는 Play의 대시보드 확인.
</Accordion>

<Accordion title="크레딧은 Play와 API 간에 공유되나요?">
  네. 동일한 잔액이 양쪽에 적용됩니다. 클론드 보이스 호출도 프리셋 보이스와 동일한 방식으로 크레딧을 차감합니다.
</Accordion>

## 오류와 트러블슈팅

<Accordion title="가장 흔한 오류는 무엇인가요?">
  * **401** — API Key 누락 또는 잘못된 키
  * **402** — 크레딧 부족
  * **403** — 이 계정 소유가 아닌 보이스
  * **400** — 요청 본문 문제(필드 누락, 잘못된 enum, raw API에서 300자 초과 등)
  * **429** — 요청 수 제한 도달

  전체 레퍼런스는 [오류 처리](/ko/docs/production/error-handling)를 확인해 주세요.
</Accordion>

<Accordion title="호출이 계속 실패합니다. 어디부터 확인해야 하나요?">
  다음 순서로 확인하세요.

  1. `x-sup-api-key` 헤더가 앞뒤 공백 없이 설정되어 있는지.
  2. POST 요청에 `Content-Type: application/json`이 설정되어 있는지.
  3. `voice_id`가 이 계정의 실제 ID인지(`GET /v1/voices` 또는 `GET /v1/custom-voices`로 확인).
  4. `text`, `language`, `style`이 해당 보이스가 지원하는 값과 일치하는지.

  문제가 계속되면 요청 본문, 헤더, 발생 시각을 포함하여 [고객 지원](/ko/docs/resources/support)에 문의해 주세요.
</Accordion>

<Accordion title="요청 수 제한은 어떻게 되나요?">
  기본값은 티어에 따라 분당 20 / 30 / 60회입니다. 보이스 클로닝은 분당 10회입니다. 자세한 내용은 [요청 수 제한](/ko/docs/production/rate-limits)을 참고해 주세요.
</Accordion>

## 운영

<Accordion title="누구나 API를 사용할 수 있나요?">
  네 — 콘솔에 가입하면 바로 시작할 수 있습니다. 별도의 승인 절차는 없습니다.
</Accordion>

<Accordion title="엔터프라이즈 플랜도 있나요?">
  네. 팀 단위 사용, 상향된 요청 제한, 하위 사용자 계정, 전용 처리 용량이 필요한 경우 [엔터프라이즈 문의](https://docs.google.com/forms/d/1YexQpjpK0ZEou12blTytkZLqvrV-Uv95GbhxoOQ54R8/edit)를 통해 신청해 주세요.
</Accordion>

<Accordion title="버그를 보고하거나 도움을 받으려면 어디로 문의하나요?">
  [고객 지원](https://support.supertone.ai/hc/en-us/categories/10267196754959-Play) 페이지에서 1:1 문의를 남겨주세요. 요청 페이로드, 헤더, 타임스탬프를 함께 전달해 주시면 더 빠르게 해결해 드릴 수 있습니다.
</Accordion>