> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt > Use this file to discover all available pages before exploring further. # 음성 모델 목록 조회 > `agent.data.voice`에 사용할 수 있는 음성 모델 목록을 조회합니다. 조직 전용 보이스도 포함합니다. 다음 페이지는 `next_cursor`를 `cursor`로 다시 전달해 조회합니다. `is_public: false`는 삭제 가능한 조직 전용 보이스를 나타냅니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json get /models/voices openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 조직 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 캠페인 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /models/voices: get: tags: - Models summary: 음성 모델 목록 조회 description: >- `agent.data.voice`에 사용할 수 있는 음성 모델 목록을 조회합니다. 조직 전용 보이스도 포함합니다. 다음 페이지는 `next_cursor`를 `cursor`로 다시 전달해 조회합니다. `is_public: false`는 삭제 가능한 조직 전용 보이스를 나타냅니다. operationId: listVoiceModels parameters: - name: provider in: query required: false schema: anyOf: - type: string - type: 'null' description: >- 음성 provider 필터입니다. 허용값에는 `google`, `elevenlabs`, `cartesia`, `openai` 등이 있습니다. title: Provider description: >- 음성 provider 필터입니다. 허용값에는 `google`, `elevenlabs`, `cartesia`, `openai` 등이 있습니다. - name: language in: query required: false schema: anyOf: - type: string - type: 'null' description: 음성 언어 필터입니다. `ko-KR`, `*`처럼 이 endpoint가 반환한 값을 사용합니다. title: Language description: 음성 언어 필터입니다. `ko-KR`, `*`처럼 이 endpoint가 반환한 값을 사용합니다. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor description: 이전 응답의 `next_cursor` 값입니다. 다음 페이지를 조회할 때 그대로 전달합니다. description: 이전 응답의 `next_cursor` 값입니다. 다음 페이지를 조회할 때 그대로 전달합니다. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Limit description: 반환할 최대 항목 수입니다. v3 목록 endpoint는 1~100을 허용합니다. description: 반환할 최대 항목 수입니다. v3 목록 endpoint는 1~100을 허용합니다. responses: '200': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/ListVoiceModelsResponse' '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 리소스를 찾을 수 없습니다. value: error: code: RESOURCE_NOT_FOUND message: Resource not found. details: resource: agent '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌이 발생했습니다. value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: 요청 한도를 초과했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 5 window_seconds: 1 '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} security: - BearerAuth: [] components: schemas: ListVoiceModelsResponse: properties: items: items: $ref: '#/components/schemas/VoiceModelResponse' type: array title: Items description: 페이지 항목입니다. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 다음 페이지 커서입니다. 조회할 항목이 더 없으면 null입니다. total_count: type: integer title: Total Count description: 조건에 맞는 전체 항목 수입니다. type: object required: - items - total_count title: ListVoiceModelsResponse description: Voice 모델 카탈로그 (public + 현재 조직 private). ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. VoiceModelResponse: properties: provider: type: string title: Provider description: TTS 공급사. id: type: string title: Id description: 공급사 내 음성 식별자. 에이전트 설정의 `data.voice.id`에 지정하는 값입니다. name: type: string title: Name description: 사람이 읽는 음성 이름. language: type: string title: Language description: >- BCP-47 locale code입니다. 음성 선택 시 `agent.data.voice.language`에 이 값을 사용합니다. is_public: type: boolean title: Is Public description: >- 이 보이스가 공개 카탈로그에 포함되는지 여부입니다. `false`이면 조직 전용으로 생성한 보이스 클론이며, `DELETE /v3/models/voices/{voice_id}`로 삭제할 수 있는 유일한 유형입니다. 공개 카탈로그 보이스는 삭제할 수 없습니다. gender: anyOf: - type: string enum: - male - female - type: 'null' title: Gender description: provider가 제공하는 경우 포함되는 음성 gender 메타데이터입니다. sample_url: anyOf: - type: string - type: 'null' title: Sample Url description: 사용 가능한 경우 제공되는 sample audio clip URL입니다. description: anyOf: - type: string - type: 'null' title: Description description: 사람이 읽을 수 있는 설명입니다. model: anyOf: - type: string - type: 'null' title: Model description: 'TTS 공급사 내 모델명 (예: eleven_turbo_v2_5).' capabilities: anyOf: - additionalProperties: true type: object - type: 'null' title: Capabilities description: 지원되는 속도나 볼륨 범위 같은 voice parameter capability hint입니다. type: object required: - provider - id - name - language - is_public title: VoiceModelResponse description: 단일 Voice 모델 엔트리. ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '조직 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````