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

# 보이스 추천

> 텍스트 묘사를 기반으로 조건에 맞는 타입캐스트 보이스를 추천하는 API입니다.

`voice_id`를 직접 조회할 필요 없이, 원하는 스타일·분위기·언어·사용 사례 등의 키워드나 문장으로 보이스를 검색할 수 있습니다. 응답은 추천 점수 순서로 정렬되며, 상위 후보의 `voice_id`를 `POST /v1/text-to-speech` 같은 텍스트 음성 변환 엔드포인트에 바로 전달할 수 있습니다.

응답에는 `voice_id`, `voice_name`, `score`만 포함됩니다. 추천된 보이스의 지원 모델, 감정, 성별, 나이대, 사용 사례 같은 상세 메타데이터가 필요하면 `GET /v2/voices` 또는 `GET /v2/voices/{voice_id}`를 함께 호출하세요.



## OpenAPI

````yaml /ko/api-reference/openapi.json get /v1/voices/recommendations
openapi: 3.1.0
info:
  title: Typecast API
  version: 0.1.2
  x-logo:
    url: https://typecast.ai/_ipx/_/image/logo/tc_logo.webp
servers:
  - url: https://api.typecast.ai
    description: 프로덕션 서버
security:
  - ApiKeyAuth: []
paths:
  /v1/voices/recommendations:
    get:
      tags:
        - Voices
      summary: 보이스 추천
      description: >-
        텍스트 묘사를 기반으로 조건에 맞는 타입캐스트 보이스를 추천하는 API입니다.


        `voice_id`를 직접 조회할 필요 없이, 원하는 스타일·분위기·언어·사용 사례 등의 키워드나 문장으로 보이스를 검색할 수
        있습니다. 응답은 추천 점수 순서로 정렬되며, 상위 후보의 `voice_id`를 `POST /v1/text-to-speech`
        같은 텍스트 음성 변환 엔드포인트에 바로 전달할 수 있습니다.


        응답에는 `voice_id`, `voice_name`, `score`만 포함됩니다. 추천된 보이스의 지원 모델, 감정, 성별,
        나이대, 사용 사례 같은 상세 메타데이터가 필요하면 `GET /v2/voices` 또는 `GET
        /v2/voices/{voice_id}`를 함께 호출하세요.
      operationId: recommend_voices_v1_voices_recommendations_get
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 500
            description: 텍스트 묘사. 원하는 스타일, 분위기, 언어, 사용 사례, 콘텐츠 맥락을 키워드나 문장으로 설명합니다.
            title: Query
          description: 텍스트 묘사. 원하는 스타일, 분위기, 언어, 사용 사례, 콘텐츠 맥락을 키워드나 문장으로 설명합니다.
          example: warm female voice for product tutorial
        - name: count
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10
            description: >-
              필터링 후 반환할 추천 보이스 최대 개수. 1~10 사이의 값이어야 합니다. 조건에 맞는 후보가 충분하지 않으면
              `count`보다 적은 수의 보이스가 반환될 수 있습니다.
            default: 5
            title: Count
          description: >-
            필터링 후 반환할 추천 보이스 최대 개수. 1~10 사이의 값이어야 합니다. 조건에 맞는 후보가 충분하지 않으면
            `count`보다 적은 수의 보이스가 반환될 수 있습니다.
          example: 5
      responses:
        '200':
          description: Success - Returns recommended voices sorted by score
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecommendedVoice'
                title: Response Recommend Voices V1 Voices Recommendations Get
                maxItems: 10
              example:
                - voice_id: tc_60e5426de8b95f1d3000d7b5
                  voice_name: Olivia
                  score: 0.92
                - voice_id: tc_62a8975e695ad26f7fb514d1
                  voice_name: Emma
                  score: 0.87
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Invalid API key
        '422':
          description: Validation Error - Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                  - loc:
                      - query
                      - query
                    msg: String should have at most 500 characters
                    type: string_too_long
        '500':
          description: Internal Server Error - Voice recommendation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: An unexpected error occurred
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl --request GET \
              --url 'https://api.typecast.ai/v1/voices/recommendations?query=warm%20female%20voice%20for%20product%20tutorial&count=5' \
              --header 'X-API-KEY: <api-key>'
        - lang: Python
          label: Python (requests)
          source: |
            import requests

            response = requests.get(
                "https://api.typecast.ai/v1/voices/recommendations",
                headers={"X-API-KEY": "<api-key>"},
                params={
                    "query": "warm female voice for product tutorial",
                    "count": 5,
                },
                timeout=30,
            )
            response.raise_for_status()

            recommendations = response.json()
            if recommendations:
                print(recommendations[0]["voice_id"])
components:
  schemas:
    RecommendedVoice:
      type: object
      properties:
        voice_id:
          type: string
          title: Voice Id
          description: >-
            `tc_` prefix 가 붙은 타입캐스트 보이스 식별자. 텍스트 음성 변환 요청의 `voice_id` 로 사용할 수
            있습니다.
          example: tc_60e5426de8b95f1d3000d7b5
        voice_name:
          type: string
          title: Voice Name
          description: 사람이 읽을 수 있는 보이스 이름.
          example: Olivia
        score:
          type: number
          title: Score
          description: 추천 관련도 점수. 값이 높을수록 검색어와 더 잘 맞는 후보입니다.
          example: 0.92
      required:
        - voice_id
        - voice_name
        - score
      title: RecommendedVoice
      description: '`GET /v1/voices/recommendations` 응답의 보이스 추천 후보. 관련도 순서로 정렬됩니다.'
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: 문제를 설명하는 오류 메시지
      required:
        - detail
      example:
        detail: An error occurred processing the request
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
      title: HTTPValidationError
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: 인증을 위한 API 키. 타입캐스트 API 콘솔에서 API 키를 생성할 수 있습니다.

````