> ## 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.
# Get voice
> ID로 단일 프리셋 보이스를 조회합니다.
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/api-reference/endpoints/get-voice)을 함께 확인해 주세요.
지원 언어, 스타일, 모델, 사전 렌더링된 샘플 URL을 포함한 단일 프리셋 보이스의 전체 보이스 객체를 반환합니다.
고객이 직접 클론한 보이스는 [Get custom voice](/ko/api-reference/endpoints/get-custom-voice)를 사용해 주십시오.
## 엔드포인트
```http theme={"dark"}
GET https://supertoneapi.com/v1/voices/{voice_id}
```
## 경로 파라미터
| Name | Required | Description |
| ---------- | :------: | --------------- |
| `voice_id` | ✅ | 프리셋 보이스의 ID입니다. |
## 응답
보이스 객체를 반환합니다 — 필드별 레퍼런스는 [Voices](/ko/docs/core-concepts/voices#the-voice-object)를 참고해 주십시오.
## 참고사항
* `voice_id`가 계정에 존재하지 않으면 `404 Not Found`를 반환합니다.
* 명시적 `style` 파라미터 없이 TTS를 호출하기 전에, 이 엔드포인트로 보이스의 **기본 스타일**(`styles`의 첫 번째 항목)을 확인할 수 있습니다.
## 함께 보기
보이스 객체 구조와 보이스 ID 사용 방법입니다.
전체 보이스 라이브러리를 탐색합니다.
## OpenAPI
````yaml /openapi.json get /v1/voices/{voice_id}
openapi: 3.0.0
info:
title: Supertone Public API
description: >-
Supertone API is a RESTful API for using our state-of-the-art AI voice
models.
version: 0.9.6
contact: {}
servers:
- url: https://supertoneapi.com
description: Production
security: []
tags:
- name: voices
description: Voice Library API endpoints
- name: custom_voices
description: Custom Voice Management API endpoints
- name: text_to_speech
description: Text-to-Speech API endpoints
- name: usage
description: Usage Analytics API endpoints
paths:
/v1/voices/{voice_id}:
get:
tags:
- voices
summary: Get voice details by ID
description: >-
Gets detailed information about a specific voice by its voice ID. Only
supports preset voices.
operationId: get_voice
parameters:
- name: voice_id
required: true
in: path
schema:
type: string
responses:
'200':
description: Voice details retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetCharacterByIdResponse'
'401':
description: 'Unauthorized: Invalid API key'
'404':
description: >-
Not Found: Voice not found or not accessible with the provided API
key
'500':
description: 'Internal Server Error: Failed to get voices'
security:
- api-key: []
components:
schemas:
GetCharacterByIdResponse:
type: object
properties:
voice_id:
type: string
description: Unique identifier for the voice
example:
name:
type: string
description: Name of the voice
example: Agatha
description:
type: string
description: Description of the voice
example: ''
nullable: true
age:
type: string
description: Age of the voice
example: young-adult
gender:
type: string
description: Gender of the voice
example: female
use_case:
type: string
description: Use case of the voice
example: narration
use_cases:
description: Use cases of the voice (array)
example:
- narration
- storytelling
type: array
items:
type: string
language:
description: Languages supported by the voice
example:
- ar
- bg
- cs
- da
- de
- el
- en
- es
- et
- fi
- fr
- hi
- hu
- id
- it
- ja
- ko
- nl
- pl
- pt
- ro
- ru
- vi
type: array
items:
type: string
styles:
description: Styles available for the voice
example:
- kind-default
- normal
- serene
type: array
items:
type: string
models:
description: Models available for the voice
example:
- sona_speech_1
- sona_speech_2
- sona_speech_2_flash
- supertonic_api_1
- supertonic_api_3
type: array
items:
type: string
samples:
description: URL to the sample audio file for the voice
type: array
items:
$ref: '#/components/schemas/APISampleData'
thumbnail_image_url:
type: string
description: URL to the thumbnail image for the voice
example: https://example.com/thumbnails/voice-thumbnail.png
required:
- voice_id
- name
- age
- gender
- use_case
- use_cases
- language
- styles
- models
APISampleData:
type: object
properties:
language:
type: string
description: Language of the sample
example: ko
style:
type: string
description: Style of the sample
example: kind-default
model:
type: string
description: Model of the sample
example: supertonic_api_3
url:
type: string
description: URL to the sample audio file
example: https://example.com/samples/sample-audio.wav
required:
- language
- style
- model
- url
securitySchemes:
api-key:
type: apiKey
in: header
name: x-sup-api-key
````