POST

/services/aigc/text2image/image-synthesis

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wanx-v1",
    "input": {
        "prompt": "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。"
    },
    "parameters": {
        "style": "<auto>",
        "size": "1024*1024",
        "n": 1
    }
}'

{
  "code": "InvalidApiKey",
  "message": "No API-key provided.",
  "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

请先获取 API Key 并设置为环境变量。如需使用 SDK，请先安装 SDK。

wanx-v1 已停止迭代更新，推荐升级至 Wan 文生图 V2 以获取更好的效果。

鉴权

string

header

必填

千问云 API Key。详见获取 API Key。

Header 参数

删除音色

Qwen

创建音色

通过文本描述创建自定义音色，并返回预览音频。

POST

/services/audio/tts/customization

cURL

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "qwen-voice-design",
  "input": {
    "action": "create",
    "target_model": "qwen3-tts-vd-realtime-2026-01-15",
    "voice_prompt": "语速适中，音调偏高，充满活力",
    "preview_text": "你好，欢迎使用声音设计功能。",
    "preferred_name": "mydesign"
  }
}'

{
  "output": {
    "voice": "qwen-tts-vd-announcer-voice-20251201102800-a1b2",
    "preview_audio": {
      "data": "{base64_encoded_audio}",
      "sample_rate": 24000,
      "response_format": "wav"
    },
    "target_model": "qwen3-tts-vd-realtime-2026-01-15"
  },
  "usage": {
    "count": 1
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

model 是设计模型（固定为 qwen-voice-design）。target_model 是驱动所创建音色的合成模型。后续合成调用中的 model 必须与 target_model 一致，不匹配会导致调用失败。

鉴权

string

header

必填

千问云 API Key。详见获取 API Key。

请求体

application/json

enum<string>

必填

语音设计模型，固定值为 qwen-voice-design。

可选值：qwen-voice-design

示例:qwen-voice-design

object

必填

显示子属性

enum<string>

必填

操作类型，固定值为 create。

可选值：create

示例:create

enum<string>

必填

音色绑定的合成模型，后续合成调用时需传入相同模型。可选值：qwen3-tts-vd-realtime-2026-01-15、qwen3-tts-vd-realtime-2025-12-16（实时），qwen3-tts-vd-2026-01-26（非实时）。

可选值：qwen3-tts-vd-realtime-2026-01-15,qwen3-tts-vd-realtime-2025-12-16,qwen3-tts-vd-2026-01-26

示例:qwen3-tts-vd-realtime-2026-01-15

string

必填

音色描述文本，最多 2,048 个字符，仅支持中英文。参见如何撰写有效的音色描述。

示例:A composed middle-aged male announcer with a deep, rich and magnetic voice, suitable for news broadcasting.

取值范围：length <= 2048

string

必填

用于生成预览音频的文本，最多 1,024 个字符，须使用支持的语言。

示例:Dear listeners, hello everyone. Welcome to the evening news.

取值范围：length <= 1024

string

音色名称关键词（仅支持字母、数字和下划线，最多 16 个字符），会出现在生成的音色名称中。例如传入 announcer，生成的名称为 qwen-tts-vd-announcer-voice-20251201102800-a1b2。

示例:announcer

取值范围：length <= 16pattern: ^[a-zA-Z0-9_]+$

enum<string>

默认值"zh"

生成音色的语言代码，须与

enum<string>

必填

必须设置为 enable 以创建异步任务。如未设置，将返回错误："current user api does not support synchronous calls"。

可选值：enable

string

指定工作空间，格式为 ws_{workspaceId}。

请求体

application/json

string

必填

模型名称。

示例:wanx-v1

object

必填

输入内容。

显示子属性

string

必填

正向文本描述，即期望图像中出现的内容。最大 800 个字符。

取值范围：length <= 800

string

反向文本描述，即不希望图像中出现的内容。最大 500 个字符。

取值范围：length <= 500

string

参考图像 URL。支持 JPG、PNG、BMP、TIFF、WEBP 格式，大小不超过 10 MB，分辨率在 256×256 至 4096×4096 之间，URL 不能包含中文字符。

object

生成参数（可选）。

显示子属性

enum<string>

默认值"<auto>"

图像风格。

可选值：<auto>,<photography>,<portrait>,<3d cartoon>,<anime>,<oil painting>,<watercolor>,<sketch>,<chinese painting>,<flat illustration>

enum<string>

默认值"1024*1024"

图像分辨率，格式为 宽*高。

可选值：1024*1024,720*1280,768*1152,1280*720

integer

默认值4

生成图像数量。

取值范围：1 <= x <= 4

integer

随机种子，用于结果复现。范围 [0, 2147483647]。

取值范围：0 <= x <= 2147483647

number

参考图强度，控制生成图像与参考图的相似程度。范围 [0.0, 1.0]，值越大越相似。

取值范围：0 <= x <= 1

enum<string>

默认值"repaint"

参考图模式。repaint 基于参考图内容生成，refonly 基于参考图风格生成。

可选值：repaint,refonly

响应

4XX-application/json

string

错误码。

string

错误信息。

string

请求唯一标识。

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wanx-v1",
    "input": {
        "prompt": "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。"
    },
    "parameters": {
        "style": "<auto>",
        "size": "1024*1024",
        "n": 1
    }
}'

{
  "code": "InvalidApiKey",
  "message": "No API-key provided.",
  "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

object

显示子属性

enum<integer>

默认值24000

预览音频的采样率（Hz）。

可选值：8000,16000,24000,48000

示例:24000

enum<string>

默认值"wav"

预览音频的输出格式。

可选值：pcm,wav,mp3,opus

示例:wav

响应

200-application/json

object

显示子属性

string

生成的音色名称，合成 API 调用时将此值作为 voice 参数传入。

示例:qwen-tts-vd-announcer-voice-20251201102800-a1b2

object

显示子属性

string

Base64 编码的预览音频，解码后可得到音频文件。

示例:{base64_encoded_audio}

integer

预览音频的采样率。

示例:24000

string

预览音频的格式。

示例:wav

string

与该音色绑定的合成模型。

示例:qwen3-tts-vd-realtime-2026-01-15

object

显示子属性

integer

本次计费的音色创建次数，创建成功固定为 1。

示例:1

string

请求 ID，用于问题排查。

示例:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx