{
  "hf_id": "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
  "meta": {
    "title": "Qwen3-TTS-12Hz-1.7B-CustomVoice",
    "slug": "qwen3-tts-12hz-1.7b-customvoice",
    "provider": "Qwen",
    "description": "Text-to-speech served via vLLM-Omni with predefined speaker voices and optional style/emotion control, exposed through the OpenAI /v1/audio/speech API. Sibling VoiceDesign and Base (voice-clone) checkpoints share the same serving path.",
    "date_added": "2026-06-17",
    "date_updated": "2026-06-15",
    "tasks": [
      "omni"
    ],
    "related_recipes": [
      "mistralai/Voxtral-4B-TTS-2603",
      "fishaudio/s2-pro",
      "stabilityai/stable-audio-open-1.0"
    ]
  },
  "model": {
    "model_id": "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    "min_vllm_version": "0.20.0",
    "architecture": "dense",
    "parameter_count": "1.7B",
    "active_parameters": "1.7B",
    "context_length": 0,
    "base_args": [
      "--omni"
    ],
    "base_env": {},
    "install": {
      "pip": {
        "command": "uv venv\nsource .venv/bin/activate\nuv pip install -U vllm --torch-backend auto"
      },
      "docker": {
        "command": "docker pull vllm/vllm-openai:latest"
      },
      "extras": [
        {
          "note": "vLLM-Omni provides the TTS serving backend and the `--omni` serve path. See the installation guide for pre-built wheels or building from source.",
          "command": "uv pip install git+https://github.com/vllm-project/vllm-omni.git"
        }
      ]
    }
  },
  "omni": {
    "tasks": [
      {
        "id": "t2a",
        "label": "Text → Speech",
        "endpoint": "/v1/audio/speech",
        "description": "CustomVoice TTS via the OpenAI /v1/audio/speech API",
        "curl": "curl -X POST http://localhost:8000/v1/audio/speech \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice\",\n    \"input\": \"Hello, how are you?\",\n    \"voice\": \"vivian\",\n    \"language\": \"English\",\n    \"response_format\": \"wav\"\n  }' --output output.wav\n"
      }
    ]
  },
  "features": {},
  "opt_in_features": [],
  "variants": {
    "default": {
      "precision": "bf16",
      "vram_minimum_gb": 16,
      "description": "CustomVoice 1.7B — predefined speaker voices + optional style/emotion control"
    },
    "voicedesign-1.7b": {
      "model_id": "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
      "precision": "bf16",
      "vram_minimum_gb": 16,
      "description": "VoiceDesign 1.7B — generate a voice from a natural-language description"
    },
    "base-1.7b": {
      "model_id": "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
      "precision": "bf16",
      "vram_minimum_gb": 16,
      "description": "Base 1.7B — voice cloning from reference audio + transcript"
    },
    "customvoice-0.6b": {
      "model_id": "Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice",
      "precision": "bf16",
      "vram_minimum_gb": 8,
      "description": "CustomVoice 0.6B — smaller, lower-VRAM predefined voices"
    },
    "base-0.6b": {
      "model_id": "Qwen/Qwen3-TTS-12Hz-0.6B-Base",
      "precision": "bf16",
      "vram_minimum_gb": 8,
      "description": "Base 0.6B — smaller voice-clone checkpoint"
    }
  },
  "hardware_overrides": {},
  "guide": "## Overview\n\n[Qwen3-TTS](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice) is a\ntext-to-speech family served through **vLLM-Omni** with the OpenAI-compatible\n`/v1/audio/speech` API. Three task types are each backed by a dedicated\ncheckpoint:\n\n| Task type   | Model                                       | Use case                                          |\n|-------------|---------------------------------------------|---------------------------------------------------|\n| CustomVoice | `Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice`      | Predefined speaker voices + optional style/emotion |\n| VoiceDesign | `Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign`      | Speech from a natural-language voice description   |\n| Base        | `Qwen/Qwen3-TTS-12Hz-1.7B-Base`             | Voice cloning from reference audio + transcript    |\n\nSmaller 0.6B variants are also published for CustomVoice and Base. The server\nserves **one** checkpoint at a time — switch task type by restarting with the\nmatching model.\n\n## Prerequisites\n\n- **Hardware**: a single CUDA GPU (the 1.7B talker + codec decoder share one\n  device; the bundled deploy config requests `gpu_memory_utilization: 0.3` per\n  stage).\n- **vLLM-Omni** targeting vLLM >= 0.20. See the\n  [installation guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/getting_started/installation/gpu/).\n\nUse the **Variant** selector above to switch checkpoint (CustomVoice /\nVoiceDesign / Base, 1.7B or 0.6B); the served `model_id` updates accordingly.\n\n## Installation\n\n```bash\nuv venv && source .venv/bin/activate\nuv pip install git+https://github.com/vllm-project/vllm-omni.git\n```\n\n## Launch the server\n\nThe two-stage deploy config (`vllm_omni/deploy/qwen3_tts.yaml`, async chunking\non for low first-audio latency) is auto-discovered from `model_type=qwen3_tts`:\n\n```bash\n# CustomVoice (predefined speakers)\nvllm serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --omni --port 8000\n\n# VoiceDesign (natural-language voice description)\nvllm serve Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --omni --port 8000\n\n# Base (voice cloning from reference audio)\nvllm serve Qwen/Qwen3-TTS-12Hz-1.7B-Base --omni --port 8000\n```\n\n> `--omni` is what selects the Omni pipeline, so it is required. The\n> `vllm-omni serve` console-script is equivalent only when `--omni` is passed\n> to it as well; without the flag it falls through to stock `vllm serve`.\n\n## Client usage\n\n### Predefined voice (curl)\n\n```bash\ncurl -X POST http://localhost:8000/v1/audio/speech \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\": \"Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice\", \"input\": \"Hello, how are you?\", \"voice\": \"vivian\", \"language\": \"English\"}' \\\n  --output output.wav\n```\n\n### Emotion / style instruction\n\n```bash\ncurl -X POST http://localhost:8000/v1/audio/speech \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\": \"Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice\", \"input\": \"I am so excited!\", \"voice\": \"vivian\", \"instructions\": \"Speak with great enthusiasm\"}' \\\n  --output excited.wav\n```\n\n### List available voices\n\n```bash\ncurl http://localhost:8000/v1/audio/voices\n```\n\n### Streaming PCM (low latency)\n\n```bash\ncurl -X POST http://localhost:8000/v1/audio/speech \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\": \"Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice\", \"input\": \"Hello, how are you?\", \"voice\": \"vivian\", \"language\": \"English\", \"stream\": true, \"response_format\": \"pcm\"}' \\\n  --no-buffer | play -t raw -r 24000 -e signed -b 16 -c 1 -\n```\n\nStreaming requires `stream: true` with `response_format: \"pcm\"` (24 kHz mono).\n\n### Python client and offline inference\n\n```bash\n# Online client (CustomVoice / VoiceDesign / Base)\npython examples/online_serving/text_to_speech/qwen3_tts/openai_speech_client.py \\\n  --text \"Hello, how are you?\" --speaker vivian --language English\n\n# Offline (no server)\npython examples/offline_inference/text_to_speech/qwen3_tts/end2end.py \\\n  --query-type CustomVoice [--streaming]\n```\n\n## Known limitations\n\n- Each task type requires its matching checkpoint — a CustomVoice model cannot\n  serve a Base (voice-clone) request.\n- One model variant is served per process; switching task type means restarting.\n\n## References\n\n- [Model card](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice)\n- [vLLM-Omni Qwen3-TTS online example](https://github.com/vllm-project/vllm-omni/tree/main/examples/online_serving/text_to_speech/qwen3_tts)\n- [vLLM-Omni Qwen3-TTS offline example](https://github.com/vllm-project/vllm-omni/tree/main/examples/offline_inference/text_to_speech/qwen3_tts)\n",
  "source": {
    "source": "vllm-omni",
    "repo": "vllm-project/vllm-omni",
    "ref": "main",
    "sha": "cda4a1ef83b295ba332146a7709e6277725edc9f",
    "path": "recipes/models/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice.yaml",
    "edit_url": "https://github.com/vllm-project/vllm-omni/edit/main/recipes/models/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice.yaml",
    "overlays": []
  }
}