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

# 오디오 (Audio)

> OpenAI 호환 오디오 및 Gemini 네이티브 TTS

## 소개

GravitexAI 오디오 API는 두 그룹으로 나뉩니다:

* **OpenAI 형식**: `/v1/audio/speech`(TTS), `/v1/audio/transcriptions`(STT), `/v1/audio/translations` — OpenAI Audio API와 호환
* **Gemini 네이티브 형식**: `POST /v1beta/models/{model}:generateContent`에 `responseModalities: ["AUDIO"]` 및 `speechConfig` 설정(예: `gemini-2.5-flash-preview-tts`)

Base URL: `https://api.gravitex.ai`. Gemini 인증은 [Gemini 네이티브 형식](/ko/api-reference/endpoint/gemini-native)을 참고하세요.

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer Token, 예: `Bearer sk-xxxxxxxxxx`(OpenAI 및 Gemini)
</ParamField>

<ParamField header="x-goog-api-key" type="string">
  Gemini 선택 사항: `x-goog-api-key: sk-xxxxxxxxxx`
</ParamField>

## 요청 예제

<Tabs>
  <Tab title="OpenAI 형식">
    <Tabs>
      <Tab title="텍스트-음성 변환">
        **POST** `/v1/audio/speech`

        ```bash theme={null}
        curl -X POST "https://api.gravitex.ai/v1/audio/speech" \
          -H "Authorization: Bearer sk-xxxxxxxxxx" \
          -H "Content-Type: application/json" \
          -d '{
            "model": "tts-1",
            "input": "Hello from GravitexAI.",
            "voice": "alloy",
            "response_format": "mp3"
          }' \
          --output speech.mp3
        ```
      </Tab>

      <Tab title="음성 인식">
        **POST** `/v1/audio/transcriptions`

        ```bash theme={null}
        curl -X POST "https://api.gravitex.ai/v1/audio/transcriptions" \
          -H "Authorization: Bearer sk-xxxxxxxxxx" \
          -F file="@audio.mp3" \
          -F model="whisper-1"
        ```
      </Tab>

      <Tab title="번역">
        **POST** `/v1/audio/translations`

        ```bash theme={null}
        curl -X POST "https://api.gravitex.ai/v1/audio/translations" \
          -H "Authorization: Bearer sk-xxxxxxxxxx" \
          -F file="@audio.mp3" \
          -F model="whisper-1"
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Gemini 형식">
    **POST** `/v1beta/models/{model}:generateContent`

    `{model}`을 TTS 모델 ID로 바꾸고 `generationConfig`에서 오디오 출력을 설정합니다.

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [
          {
            "parts": [
              {"text": "Say cheerfully: Have a wonderful day!"}
            ]
          }
        ],
        "generationConfig": {
          "responseModalities": ["AUDIO"],
          "speechConfig": {
            "voiceConfig": {
              "prebuiltVoiceConfig": {
                "voiceName": "Kore"
              }
            }
          }
        }
      }'
    ```

    오디오는 `candidates[0].content.parts[0].inlineData`에 반환됩니다(Base64, 주로 PCM):

    ```bash theme={null}
    echo "<base64_data>" | base64 --decode > out.pcm
    ```

    다중 화자 설정은 `speechConfig.multiSpeakerVoiceConfig`를 사용하세요 — [Google speech generation](https://ai.google.dev/gemini-api/docs/speech-generation) 참고.
  </Tab>
</Tabs>

## 공통 매개변수

### OpenAI 형식

**Speech**

* **model**: 예: `tts-1`, `tts-1-hd`
* **input**: 읽을 텍스트(최대 4096자)
* **voice**: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`

**Transcriptions / translations**

* **file**: 오디오 파일(multipart)
* **model**: 예: `whisper-1`

### Gemini 형식 (TTS)

* **model**(경로): 예: `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts`
* **contents\[].parts\[].text**: 텍스트 또는 스타일 지시
* **generationConfig.responseModalities**: `"AUDIO"` 포함 필수
* **generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName**: 예: `Kore`, `Puck`, `Charon`

<Note>
  Gemini 오디오는 `/v1/audio/*`가 아닌 `generateContent`로만 생성됩니다. 전체 매개변수는 [Gemini 네이티브 형식](/ko/api-reference/endpoint/gemini-native)을 참고하세요.
</Note>

* [OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio)
* [Gemini speech generation](https://ai.google.dev/gemini-api/docs/speech-generation)