# AudioWorld TTS API — AI Agent 실행 가이드

이 문서를 받은 AI 에이전트의 목표는 AudioWorld API를 한 번 호출해 한국어 음성 파일 `audioworld-tts-test.wav`를 만들고, 정상적인 WAV인지 검증하는 것입니다. 사용자가 설명만 요청한 경우가 아니라면 아래 절차를 실제로 실행하세요.

## 필요한 것

- 셸에서 실행 가능한 `curl`
- 환경 변수 `AUDIOWORLD_API_KEY`에 저장된 AudioWorld API 키
- API 키와 API 테스트 잔액은 [AudioWorld 계정 화면](https://play.audioworld.ai/account/?section=api)에서 준비합니다.

## 보안 규칙

1. API 키 값을 터미널 출력, 로그, 답변 또는 소스 코드에 표시하지 마세요.
2. API 키를 파일이나 Git 저장소에 쓰지 마세요.
3. 키가 설정되지 않았다면 실행을 멈추고 사용자에게 `AUDIOWORLD_API_KEY` 환경 변수를 설정해 달라고 요청하세요.
4. 키는 AudioWorld 서버에서만 사용하세요. 브라우저나 모바일 앱 코드에 포함하지 마세요.

## 바로 실행

아래 명령은 키가 설정되어 있는지만 확인한 뒤, ASMR Male 01(`asmr_male_01`) 목소리로 짧은 한국어 테스트 음성을 생성합니다.

```bash
test -n "${AUDIOWORLD_API_KEY:-}" || { echo "AUDIOWORLD_API_KEY is not set"; exit 1; }

curl --fail-with-body --silent --show-error --max-time 180 \
  https://play.audioworld.ai/v1/audio/speech \
  -H "Authorization: Bearer ${AUDIOWORLD_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "audioworld-tts-1",
    "voice": "asmr_male_01",
    "input": "안녕하세요. 오디오월드 API 테스트 음성입니다.",
    "response_format": "wav",
    "language": "Korean"
  }' \
  --output audioworld-tts-test.wav
```

## 결과 검증

WAV 파일은 처음 4바이트가 `RIFF`, 9~12번째 바이트가 `WAVE`여야 합니다.

```bash
test -s audioworld-tts-test.wav
test "$(LC_ALL=C head -c 4 audioworld-tts-test.wav)" = "RIFF"
test "$(LC_ALL=C dd if=audioworld-tts-test.wav bs=1 skip=8 count=4 2>/dev/null)" = "WAVE"
file audioworld-tts-test.wav
```

검증이 끝나면 사용자에게 HTTP 호출 성공 여부, 생성 파일 경로, 파일 크기만 알려 주세요. API 키는 절대 답변에 포함하지 마세요.

## 오류가 나면

- `401`: 키가 없거나 잘못되었거나 폐기되었습니다.
- `402`: API 테스트 잔액이 부족합니다.
- `429`: 잠시 기다린 뒤 같은 요청을 다시 시도하세요.
- `504`: 생성은 계속될 수 있습니다. 안정적인 서버 작업에서는 `Prefer: respond-async` 방식을 사용하세요.

전체 필드 정의는 [OpenAPI JSON](https://play.audioworld.ai/docs/openapi.json), 사람이 읽는 설명은 [개발자 문서](https://play.audioworld.ai/docs/)를 참고하세요.