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

# Qwen3 TTS VD

> - 텍스트를 음성 오디오로 변환하며, **[Qwen Voice Design](/ko/api-manual/audio-series/qwen-tts/qwen-voice-design)으로 생성된 커스텀 음색을 반드시 사용**해야 하며, 시스템 기본 음색은 지원하지 않습니다
- 사용 흐름: `qwen-voice-design` 호출하여 음색 생성 → `voice` 이름 획득 → 본 인터페이스의 `voice` 파라미터에 전달
- 비동기 처리 모드이며, 반환된 작업 ID로 [조회](/ko/api-manual/task-management/get-task-detail)할 수 있습니다
- 생성된 오디오 링크의 유효 기간은 24시간이므로 빠르게 저장하십시오



## OpenAPI

````yaml ko/api-manual/audio-series/qwen-tts/qwen3-tts-vd.json POST /v1/audios/generations
openapi: 3.1.0
info:
  title: Qwen3 TTS VD 음성 합성 인터페이스
  description: >-
    텍스트를 음성 오디오로 변환합니다. qwen-voice-design으로 생성된 커스텀 음색을 반드시 사용해야 하며, 시스템 기본 음색은
    지원하지 않습니다.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: 운영 환경
security:
  - bearerAuth: []
tags:
  - name: 음성 합성
    description: Qwen3 TTS VD 음성 합성 관련 인터페이스
paths:
  /v1/audios/generations:
    post:
      tags:
        - 음성 합성
      summary: Qwen3 TTS VD 음성 합성
      description: >-
        - 텍스트를 음성 오디오로 변환하며, **[Qwen Voice
        Design](/ko/api-manual/audio-series/qwen-tts/qwen-voice-design)으로 생성된
        커스텀 음색을 반드시 사용**해야 하며, 시스템 기본 음색은 지원하지 않습니다

        - 사용 흐름: `qwen-voice-design` 호출하여 음색 생성 → `voice` 이름 획득 → 본 인터페이스의
        `voice` 파라미터에 전달

        - 비동기 처리 모드이며, 반환된 작업 ID로
        [조회](/ko/api-manual/task-management/get-task-detail)할 수 있습니다

        - 생성된 오디오 링크의 유효 기간은 24시간이므로 빠르게 저장하십시오
      operationId: createQwen3TtsVd
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Qwen3TtsVdRequest'
            examples:
              basic:
                summary: 기본 호출
                value:
                  model: qwen3-tts-vd
                  prompt: 청취자 여러분, 안녕하세요. 저녁 뉴스를 시청해 주셔서 감사합니다.
                  voice: qwen-tts-vd-announcer-voice-20260402-a1b2
              with_language:
                summary: 언어 지정
                value:
                  model: qwen3-tts-vd
                  prompt: 청취자 여러분, 안녕하세요. 저녁 뉴스를 시청해 주셔서 감사합니다.
                  voice: qwen-tts-vd-announcer-voice-20260402-a1b2
                  language_type: Korean
      responses:
        '200':
          description: 음성 합성 작업 생성 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Qwen3TtsVdResponse'
        '400':
          description: 요청 파라미터 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: missing_text
                  message: 'Missing required parameter: prompt or input'
                  type: invalid_request_error
        '401':
          description: 인증되지 않음, 토큰 유효하지 않거나 만료됨
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: 크레딧 부족, 충전 필요
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: insufficient_quota
                  message: Insufficient quota. Please top up your account.
                  type: insufficient_quota
        '403':
          description: 접근 권한 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: model_access_denied
                  message: 'Token does not have access to model: qwen3-tts-vd'
                  type: invalid_request_error
        '429':
          description: 요청 빈도 초과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests, please try again later
                  type: rate_limit_error
        '500':
          description: 서버 내부 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: Internal server error
                  type: api_error
components:
  schemas:
    Qwen3TtsVdRequest:
      type: object
      required:
        - model
        - prompt
        - voice
      properties:
        model:
          type: string
          description: 모델 이름
          enum:
            - qwen3-tts-vd
          default: qwen3-tts-vd
          example: qwen3-tts-vd
        prompt:
          type: string
          description: |-
            합성할 텍스트

            **제약:**
            - 최대 `600`자
          maxLength: 600
          example: 청취자 여러분, 안녕하세요. 저녁 뉴스를 시청해 주셔서 감사합니다.
        voice:
          type: string
          description: >-
            음색 이름


            - 먼저 [Qwen Voice
            Design](/ko/api-manual/audio-series/qwen-tts/qwen-voice-design)을 통해
            음색을 생성해야 합니다

            - Voice Design 작업 결과의 `result_data.voice`에서 획득

            - 시스템 기본 음색은 지원하지 않음
          example: qwen-tts-vd-announcer-voice-20260402-a1b2
        language_type:
          type: string
          description: |-
            언어 힌트, 모델이 발음 규칙을 선택하는 데 도움

            미전달 시 자동 감지
          enum:
            - Auto
            - Chinese
            - English
            - Japanese
            - Korean
            - French
            - German
            - Spanish
            - Italian
            - Russian
            - Portuguese
          example: Auto
        callback_url:
          type: string
          description: >-
            작업 완료 후 HTTPS 콜백 주소


            **콜백 시점:**

            - 작업 완료(completed), 실패(failed) 또는 취소(cancelled) 시 트리거

            - 과금 확인 완료 후 발송


            **보안 제한:**

            - HTTPS 프로토콜만 지원

            - 내부 IP 주소로의 콜백 금지(127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x
            등)

            - URL 길이 `2048`자 이하


            **콜백 메커니즘:**

            - 타임아웃: `10`초

            - 실패 후 최대 `3`회 재시도(각각 실패 후 `1`초/`2`초/`4`초 후 재시도)

            - 콜백 응답 본문 형식은 작업 조회 인터페이스 반환 형식과 동일

            - 콜백 주소가 2xx 상태 코드를 반환하면 성공으로 간주, 그 외 상태 코드는 재시도 트리거
          format: uri
          example: https://your-domain.com/webhooks/tts-completed
    Qwen3TtsVdResponse:
      type: object
      properties:
        created:
          type: integer
          description: 작업 생성 타임스탬프
          example: 1775122733
        id:
          type: string
          description: 작업 ID
          example: task-unified-1775122733-lozyt2i5
        model:
          type: string
          description: 실제 사용된 모델 이름
          example: qwen3-tts-vd
        object:
          type: string
          enum:
            - audio.generation.task
          description: 작업의 구체적인 유형
        progress:
          type: integer
          description: 작업 진행률 (0-100)
          minimum: 0
          maximum: 100
          example: 0
        status:
          type: string
          description: 작업 상태
          enum:
            - pending
            - processing
            - completed
            - failed
          example: pending
        task_info:
          $ref: '#/components/schemas/AudioTaskInfo'
          description: 오디오 작업 상세 정보
        type:
          type: string
          enum:
            - audio
          description: 작업의 출력 유형
          example: audio
        usage:
          $ref: '#/components/schemas/AudioUsage'
          description: 사용량 및 과금 정보
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: 오류 코드 식별자
            message:
              type: string
              description: 오류 설명 메시지
            type:
              type: string
              description: 오류 유형
    AudioTaskInfo:
      type: object
      properties:
        can_cancel:
          type: boolean
          description: 작업 취소 가능 여부
          example: true
        estimated_time:
          type: integer
          description: 예상 완료 시간(초)
          minimum: 0
          example: 10
        audio_type:
          type: string
          description: 오디오 작업 유형
          example: tts
    AudioUsage:
      type: object
      description: 사용량 정보
      properties:
        credits_reserved:
          type: number
          description: 예상 소모 크레딧 수
          minimum: 0
          example: 0.32
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ##모든 인터페이스는 Bearer Token 인증이 필요합니다##

        **API Key 발급:**

        [API Key 관리 페이지](https://evolink.ai/dashboard/keys)에서 API Key를 발급받으세요

        **요청 헤더에 다음을 추가하세요:**
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````