How to make Qwen generate a JSON string-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

When performing information extraction or structured data generation tasks, a model may return extra text (such as ```json ) that breaks downstream parsing. Enabling structured output ensures the model returns a valid JSON string. The JSON Schema mode also gives you precise control over the output structure and types, eliminating extra validation or retries.

Usage

Structured output supports two modes: JSON Object and JSON Schema.

JSON Object mode: Ensures the output is a valid JSON string, but does not guarantee a specific structure. Usage:
1. Set theresponse_formatparameter: In the request body, set response_format to {"type": "json_object"}.
2. Include the JSON keyword in your prompt: The system message or user message must contain the word "JSON" (case-insensitive), otherwise the API returns: 'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.
JSON Schema mode: Ensures the output conforms to a specified structure. Usage: set response_format to {"type": "json_schema", "json_schema": {..., "strict": true}}.

No JSON keyword required in the prompt.

The parameters above apply to the Chat Completions API. If you use the Responses API, set text.format instead; the value format is the same. See the examples below. In JSON Object mode, the Responses API also requires the prompt to contain the word "JSON"; otherwise, a 400 error is returned.

Feature comparison:

Feature	JSON Object mode	JSON Schema mode
Outputs valid JSON	Yes	Yes
Strictly follows schema	No	Yes
Supported models	Most Qwen models, Kimi, GLM, DeepSeek, Stepfun	Only supported by some models
`response_format` setting	`{"type": "json_object"}`	`{"type": "json_schema", "json_schema": {..., "strict": true}}`
Prompt requirement	Must include "JSON"	Recommended to describe explicitly
Use case	Flexible JSON output	Precise schema validation

Supported models

NoteModels labeled "non-thinking mode" support structured output only in non-thinking mode.

JSON Object

Qwen

Text generation models
- Qwen-Max: Qwen3.8-Max series, Qwen3.7-Max series
- Qwen-Max (non-thinking mode): Qwen3.6-Max series, Qwen3-Max series, Qwen-Max series
- Qwen-Plus: Qwen3.7-Plus series
- Qwen-Plus (non-thinking mode): Qwen3.6-Plus series, Qwen3.5-Plus series, Qwen-Plus series
- Qwen-Flash: Qwen3.8-Flash series, Qwen3.7-Flash series
- Qwen-Flash (non-thinking mode): Qwen3.6-Flash series, Qwen3.5-Flash series, Qwen-Flash series
- Qwen-Turbo (non-thinking mode): Qwen-Turbo series
- Qwen-Coder: Qwen3-Coder series
- Qwen-Long: Qwen-Long series
- Qwen3.8 open-source series
- Qwen3.6 open-source series (non-thinking mode)
- Qwen3.5 open-source series (non-thinking mode)
- Qwen3 open-source series (non-thinking mode)
- Qwen3-Coder open-source series
- Qwen2.5 open-source series (excluding math and coder models)
Multimodal models
- Qwen-VL (non-thinking mode): Qwen3-VL-Plus series, Qwen3-VL-Flash series, Qwen-VL-Max series (excluding the latest and snapshot versions), Qwen-VL-Plus series (excluding the latest and snapshot versions)
- Qwen-Omni: Qwen3.8-Omni-Flash, Qwen3.5-Omni-Plus series
- Qwen3-VL open-source series (non-thinking mode)

Kimi

Deployed on Alibaba Cloud Model Studio
- kimi-k3.1-pro
- kimi-k3
Deployed by Moonshot AI
- kimi/kimi-k3.1-pro, kimi/kimi-k3.1-pro-highspeed, kimi/kimi-k3, kimi/kimi-k2.7-code-highspeed, kimi/kimi-k2.7-code, kimi/kimi-k2.6, kimi/kimi-k2.5

DeepSeek

Deployed on Alibaba Cloud Model Studio
- deepseek-v4-pro
- deepseek-v4.1-flash
- deepseek-v4.1-flash-1017
Deployed by Kuaishou Wanqing
- vanchin/deepseek-v3.2-think, vanchin/deepseek-v3, vanchin/deepseek-ocr

GLM

glm-5.1
Non-thinking mode: glm-5

Stepfun

Thinking mode only: stepfun/step-3.7-flash, stepfun/step-5-preview

Ling

Deployed on AntDigital
- antdigital/Ling-3.1-flash

JSON Schema

Qwen3.7-Plus series, Qwen3.8-Flash series, Qwen3.7-Flash series, Qwen3.7-Max series, and Qwen3.8-Max series models

Getting started

This example extracts structured information from a personal profile.

JSON Object mode does not guarantee stable key names or field types. Results may vary across different prompts or calls. To enforce a fixed structure, use JSON Schema mode.

Obtain an API key and export the API key as an environment variable. If you use the OpenAI SDK or DashScope SDK to make calls, install the SDK.

OpenAI-compatible Chat Completions API

Python

from openai import OpenAI
import os

client = OpenAI(
    # If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx"
    # API keys differ by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # This is the Beijing region base_url. If you use Singapore region models, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "system",
            "content": "Extract the user's name and age, and return them in JSON format"
        },
        {
            "role": "user",
            "content": "Hi everyone, my name is Alex Brown, I'm 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling",
        },
    ],
    response_format={"type": "json_object"}
)

json_string = completion.choices[0].message.content
print(json_string)

Response

{
  "Name": "Alex Brown",
  "Age": 34
}

Node.js

import OpenAI from "openai";

const openai = new OpenAI({
    // If you haven't configured an environment variable, replace the next line with: apiKey: "sk-xxx"
    // API keys differ by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
    apiKey: process.env.DASHSCOPE_API_KEY,
    // This is the Beijing region base_url. If you use Singapore region models, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
});

const completion = await openai.chat.completions.create({
    model: "qwen3.8-max",
    messages: [
        {
            role: "system",
            content: "Extract the user's name and age, and return them in JSON format"
        },
        {
            role: "user",
            content: "Hi everyone, my name is Alex Brown, I'm 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling"
        }
    ],
    response_format: {
        type: "json_object"
    }
});

const jsonString = completion.choices[0].message.content;
console.log(jsonString);

Response

{
  "name": "Alex Brown",
  "age": 34
}

curl

# ======= Important notes =======
# API keys differ by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# This is the Beijing region base_url. If you use Singapore region models, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
# === Delete this comment before running ===
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3.8-max",
    "messages": [
        {
            "role": "system",
            "content": "Extract the user'\''s name and age, and return them in JSON format"
        },
        {
            "role": "user",
            "content": "Hi everyone, my name is Alex Brown, I'\''m 34 years old, my email is alexbrown@example.com"
        }
    ],
    "response_format": {
        "type": "json_object"
    }
}'

Response

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "{\"name\":\"Alex Brown\",\"age\":\"34 years old\"}"
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 207,
        "completion_tokens": 20,
        "total_tokens": 227,
        "prompt_tokens_details": {
            "cached_tokens": 0
        }
    },
    "created": 1756455080,
    "system_fingerprint": null,
    "model": "qwen3.8-max",
    "id": "chatcmpl-624b665b-fb93-99e7-9ebd-bb6d86d314d2"
}

OpenAI-Compatible Responses API

The Responses API is the successor to the Chat Completions API. Structured output is configured with the text.format parameter. For parameter details and the migration guide, see OpenAI-compatible Responses.

Python

from openai import OpenAI
import os

client = OpenAI(
    # If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the China (Beijing) region. If you use Singapore region models, replace base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
    model="qwen3.8-max",
    input="Hi everyone, my name is Alex Brown, I'm 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling. Extract the user's name and age, and return them in JSON format.",
    text={"format": {"type": "json_object"}},
)

print(response.output_text)

Response

{"name": "Alex Brown", "age": 34}

Node.js

import OpenAI from "openai";

const openai = new OpenAI({
    // If you haven't configured an environment variable, replace the next line with: apiKey: "sk-xxx"
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
});

const response = await openai.responses.create({
    model: "qwen3.8-max",
    input: "Hi everyone, my name is Alex Brown, I'm 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling. Extract the user's name and age, and return them in JSON format.",
    text: { format: { type: "json_object" } }
});

console.log(response.output_text);

Response

{"name": "Alex Brown", "age": 34}

curl

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3.8-max",
    "input": "Hi everyone, my name is Alex Brown, I'\''m 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling. Extract the user'\''s name and age, and return them in JSON format.",
    "text": {
        "format": {
            "type": "json_object"
        }
    }
}'

Response

{
    "id": "resp_3b59521f-fbef-9873-9c54-c3fdc94da946",
    "created_at": 1793277220,
    "model": "qwen3.8-max",
    "object": "response",
    "output": [
        {
            "id": "reasoning_3a4a1e6d-2a2f-4c3f-a3ea-0f0a5c1b9f11",
            "summary": [
                {
                    "text": "We need answer user request. Need output JSON only.",
                    "type": "summary_text"
                }
            ],
            "type": "reasoning"
        },
        {
            "id": "msg_acbe8467-497c-4c09-8584-dae4a1c97f9b",
            "content": [
                {
                    "annotations": [],
                    "text": "{\"name\": \"Alex Brown\", \"age\": 34}",
                    "type": "output_text",
                    "logprobs": null
                }
            ],
            "role": "assistant",
            "status": "completed",
            "type": "message"
        }
    ],
    "status": "completed",
    "text": {
        "format": {
            "type": "json_object"
        },
        "verbosity": null
    },
    "usage": {
        "input_tokens": 123,
        "output_tokens": 118,
        "output_tokens_details": {
            "reasoning_tokens": 95
        },
        "total_tokens": 241
    }
}

DashScope API

Python

import os
import dashscope

# The following configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# If you use Singapore region models, replace the region with ap-southeast-1
client = dashscope.Client(
    # If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx" (Alibaba Cloud Model Studio API key),
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)
messages=[
    {
        "role": "system",
        "content": [{"text": "Extract the user's name and age, and return them in JSON format"}]
    },
    {
        "role": "user",
        "content": [{"text": "Hi everyone, my name is Alex Brown, I'm 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling"}],
    },
]
response = client.multimodal.chat.create(
    model="qwen3.8-max",
    messages=messages,
    response_format={'type': 'json_object'}
    )
json_string = response.choices[0].message.content
print(json_string)

Response

{
  "name": "Alex Brown",
  "age": 34
}

Java

DashScope Java SDK version must be 2.21.4 or higher.

import java.util.Arrays;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.common.ResponseFormat;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    // To use models in the Singapore region, uncomment the following line
    // static {Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";}
    public static void simpleMultiModalConversationCall()
            throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("text", "Extract the user's name and age, and return them in JSON format"))).build();
        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("text", "Hi everyone, my name is Alex Brown, I'm 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling"))).build();
        ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // If you have not configured an environment variable, replace the following line with: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen3.8-max")
                .messages(Arrays.asList(systemMessage, userMessage))
                .responseFormat(jsonMode)
                .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
    }
    public static void main(String[] args) {
        try {
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
    }
}

Response

{
  "name": "Alex Brown",
  "age": 34
}

curl

# ======= Important notes =======
# API keys differ by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# This is the Beijing region URL. If you use Singapore region models, replace the URL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
# === Delete this comment before running ===
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3.8-max",
    "input": {
        "messages": [
            {
                "role": "system",
                "content": "Extract the user'\''s name and age, and return them in JSON format"
            },
            {
                "role": "user",
                "content": "Hi everyone, my name is Alex Brown, I'\''m 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling"
            }
        ]
    },
    "parameters": {
        "response_format": {
            "type": "json_object"
        }
    }
}'

Response

{
  "name": "Alex Brown",
  "age": 34
}

Thinking models such as qwen3.8-max enable deep thinking by default, so structured output needs no extra enable_thinking setting. To separate the reasoning process from the final answer in streaming responses, see Streaming output for thinking models.

Image and video data processing

Multimodal models also support structured output for images and videos. Use JSON mode to extract structured data from visual content, such as field values from receipts, object locations in images, or events in video.

For image and video file limits, see Image and video understanding .

OpenAI compatible

Python

import os
from openai import OpenAI

client = OpenAI(
    # If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx" (Alibaba Cloud Model Studio API key),
    # API keys differ by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # This is the Beijing region base_url. If you use Singapore region models, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "system",
            "content": [{"type": "text", "text": "You are a helpful assistant."}],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"
                    },
                },
                {"type": "text", "text": "Extract ticket (array type, including travel_date, trains, seat_num, arrival_site, price) and invoice information (array type, including invoice_code and invoice_number) from the image. Output a JSON containing both ticket and invoice arrays"},
            ],
        },
    ],
    response_format={"type": "json_object"}
)
json_string = completion.choices[0].message.content
print(json_string)

Response

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "stream",
      "seat_num": "371",
      "arrival_site": "Development Zone",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

Node.js

import OpenAI from "openai";

const openai = new OpenAI({
  // If you haven't configured an environment variable, replace the next line with: apiKey: "sk-xxx" (Model Studio API key)
  // API keys differ by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
  apiKey: process.env.DASHSCOPE_API_KEY,
  // This is the Beijing region base_url. If you use Singapore region models, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
  baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
});

async function main() {
  const response = await openai.chat.completions.create({
    model: "qwen3.8-max",
    messages: [{
        role: "system",
        content: [{
          type: "text",
          text: "You are a helpful assistant."
        }]
      },
      {
        role: "user",
        content: [{
            type: "image_url",
            image_url: {
              "url": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"
            }
          },
          {
            type: "text",
            text: "Extract ticket (array type, including travel_date, trains, seat_num, arrival_site, price) and invoice information (array type, including invoice_code and invoice_number) from the image. Output a JSON containing both ticket and invoice arrays"
          }
        ]
      }
    ],
    response_format: {type: "json_object"}
  });
  console.log(response.choices[0].message.content);
}

main()

Response

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "stream",
      "seat_num": "371",
      "arrival_site": "Development Zone",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

curl

# ======= Important notes =======
# API keys differ by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# This is the Beijing region base_url. If you use Singapore region models, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
# === Delete this comment before running ===
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "qwen3.8-max",
  "messages": [
  {"role":"system",
  "content":[
    {"type": "text", "text": "You are a helpful assistant."}]},
  {
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"}},
      {"type": "text", "text": "Extract ticket (array type, including travel_date, trains, seat_num, arrival_site, price) and invoice information (array type, including invoice_code and invoice_number) from the image. Output a JSON containing both ticket and invoice arrays"}
    ]
  }],
  "response_format":{"type": "json_object"}
}'

Response

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "stream",
      "seat_num": "371",
      "arrival_site": "Development Zone",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

DashScope

Python

import os
import dashscope

# The following configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# If you use Singapore region models, replace the region with ap-southeast-1
client = dashscope.Client(
    # If you haven't configured an environment variable, replace the next line with: api_key ="sk-xxx" (Model Studio API key)
    api_key = os.getenv('DASHSCOPE_API_KEY'),
    workspace = "{WorkspaceId}",
    region = "cn-beijing",
)
messages = [
{
    "role": "system",
    "content": [
    {"text": "You are a helpful assistant."}]
},
{
    "role": "user",
    "content": [
    {"image": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"},
    {"text": "Extract ticket (array type, including travel_date, trains, seat_num, arrival_site, price) and invoice information (array type, including invoice_code and invoice_number) from the image. Output a JSON containing both ticket and invoice arrays"}]
}]
response = client.multimodal.chat.create(
    model = 'qwen3.8-max',
    messages = messages,
    response_format={'type': 'json_object'}
)
json_string = response.choices[0].message.content
print(json_string)

import os
import dashscope

# The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# If you use Beijing region models, replace the region with cn-beijing
client = dashscope.Client(
    # If you haven't configured an environment variable, replace the next line with: api_key ="sk-xxx" (Model Studio API key)
    api_key = os.getenv('DASHSCOPE_API_KEY'),
    workspace = "{WorkspaceId}",
    region = "ap-southeast-1",
)

messages = [
{
    "role": "system",
    "content": [
    {"text": "You are a helpful assistant."}]
},
{
    "role": "user",
    "content": [
    {"image": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"},
    {"text": "Extract ticket (array type, including travel_date, trains, seat_num, arrival_site, price) and invoice information (array type, including invoice_code and invoice_number) from the image. Output a JSON containing both ticket and invoice arrays"}]
}]
response = client.multimodal.chat.create(
    model = 'qwen3.8-max',
    messages = messages,
    response_format={'type': 'json_object'}
)
json_string = response.choices[0].message.content
print(json_string)

Response

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "Liushui",
      "seat_num": "371",
      "arrival_site": "Development Zone",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

Java

// DashScope Java SDK version must be 2.21.4 or higher

import java.util.Arrays;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.common.ResponseFormat;
import com.alibaba.dashscope.utils.Constants;

public class Main {

    // If you use Singapore region models, uncomment the following line
    // static {Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";}

    public static void simpleMultiModalConversationCall()
            throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("text", "You are a helpful assistant."))).build();
        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("image", "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"),
                        Collections.singletonMap("text", "Extract ticket (array type, including travel_date, trains, seat_num, arrival_site, price) and invoice information (array type, including invoice_code and invoice_number) from the image. Output a JSON containing both ticket and invoice arrays"))).build();
        ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // If you haven't configured an environment variable, replace the next line with: .apiKey("sk-xxx") (Model Studio API key)
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen3.8-max")
                .messages(Arrays.asList(systemMessage, userMessage))
                .responseFormat(jsonMode)
                .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
    }
    public static void main(String[] args) {
        try {
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
    }
}

Response

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "stream",
      "seat_num": "371",
      "arrival_site": "Development Zone",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

curl

# ======= Important notes =======
# API keys differ by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# This is the Beijing region URL. If you use Singapore region models, replace the URL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
# === Delete this comment before running ===
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "model": "qwen3.8-max",
    "input":{
        "messages":[
            {"role": "system",
         "content": [
           {"text": "You are a helpful assistant."}]},
            {
             "role": "user",
             "content": [
               {"image": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"},
               {"text": "Extract ticket (array type, including travel_date, trains, seat_num, arrival_site, price) and invoice information (array type, including invoice_code and invoice_number) from the image. Output a JSON containing both ticket and invoice arrays"}
                ]
            }
        ]
    },
    "parameters": {
        "response_format": {"type": "json_object"}
    }
}'

Response

{
  "output": {
    "choices": [
      {
        "message": {
          "content": [
            {
              "text": "{\n  \"ticket\": [\n    {\n      \"travel_date\": \"2013-06-29\",\n      \"trains\": \"train number\",\n      \"seat_num\": \"371\",\n      \"arrival_site\": \"Development Zone\",\n      \"price\": \"8.00\"\n    }\n  ],\n  \"invoice\": [\n    {\n      \"invoice_code\": \"221021325353\",\n      \"invoice_number\": \"10283819\"\n    }\n  ]\n}"
            }
          ],
          "role": "assistant"
        },
        "finish_reason": "stop"
      }
    ]
  },
  "usage": {
    "total_tokens": 598,
    "input_tokens_details": {
      "image_tokens": 418,
      "text_tokens": 68
    },
    "output_tokens": 112,
    "input_tokens": 486,
    "output_tokens_details": {
      "text_tokens": 112
    },
    "image_tokens": 418
  },
  "request_id": "b129dce1-0d5d-4772-b8b5-bd3a1d5cde63"
}

Optimize prompts

Ambiguous prompts like "return user information" lead to unpredictable output structures. For reliable results, describe the expected schema in your prompt: specify field names, types, required vs. optional status, format constraints (such as date format), and include examples.

OpenAI compatible

Python

from openai import OpenAI
import os
import json
import textwrap  # Used to handle the indentation of multi-line strings and improve code readability.

# Predefine example responses to show the model the expected output format.
# Example 1: A complete response that contains all fields.
example1_response = json.dumps(
    {
        "info": {"name": "John Doe", "age": "25 years old", "email": "johndoe@example.com"},
        "hobby": ["singing"]
    },
    ensure_ascii=False
)
# Example 2: A response that contains multiple hobbies.
example2_response = json.dumps(
    {
        "info": {"name": "Jane Smith", "age": "30 years old", "email": "janesmith@example.com"},
        "hobby": ["dancing", "swimming"]
    },
    ensure_ascii=False
)
# Example 3: A response that does not contain the hobby field (hobby is optional).
example3_response = json.dumps(
    {
        "info": {"name": "Alex Ray", "age": "28 years old", "email": "alexray@example.com"}
    },
    ensure_ascii=False
)
# Example 4: Another response that does not contain the hobby field.
example4_response = json.dumps(
    {
        "info": {"name": "Sam Wilson", "age": "35 years old", "email": "samwilson@example.com"}
    },
    ensure_ascii=False
)

# Initialize the OpenAI client.
client = OpenAI(
    # If you have not configured the environment variable, replace the following line with: api_key="sk-xxx"
    # API keys vary by region. To obtain an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the base_url for the Beijing region. If you use a model in the Singapore region, replace the base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

# The dedent function removes common leading whitespace from every line in a string.
# This lets you indent strings in your code for better readability without including the indentation in the runtime string.
system_prompt = textwrap.dedent(f"""\
    Please extract personal information from the user input and output it in the specified JSON Schema format.

    [Output Format Requirements]
    The output must strictly follow the JSON structure below:
    {{
      "info": {{
        "name": "String, required. The user's name.",
        "age": "String, required. The format must be 'number + years old', for example, '25 years old'.",
        "email": "String, required. A standard email format, for example, 'user@example.com'."
      }},
      "hobby": ["Array of strings, optional. Contains all of the user's hobbies. If no hobbies are mentioned, do not include this field in the output."]
    }}

    [Field Extraction Rules]
    1. name: Identify the user's name from the text. This field is required.
    2. age: Identify the age and convert it to the 'number + years old' format. This field is required.
    3. email: Identify the email address and keep its original format. This field is required.
    4. hobby: Identify the user's hobbies and output them as an array of strings. If no hobbies are mentioned, completely omit the hobby field.

    [Reference Examples]
    Example 1 (with hobbies):
    Q: My name is John Doe, I am 25 years old, my email is johndoe@example.com, and my hobby is singing.
    A: {example1_response}

    Example 2 (with multiple hobbies):
    Q: My name is Jane Smith, I am 30 years old, and I like dancing and swimming.
    A: {example2_response}

    Example 3 (without hobbies):
    Q: My name is Alex Ray, I am 28 years old, and my email is alexray@example.com.
    A: {example3_response}

    Example 4 (without hobbies):
    Q: I am Sam Wilson, 35 years old, email samwilson@example.com.
    A: {example4_response}

    Please strictly follow the format and rules above to extract information and output the JSON. If the user does not mention any hobbies, do not include the hobby field in the output.\
""")

# Call the model API to perform information extraction.
completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "system",
            "content": system_prompt
        },
        {
            "role": "user",
            "content": "Hello everyone, my name is Chris Lee, I am 34 years old, my email is chrislee@example.com, and I enjoy playing basketball and traveling.",
        },
    ],
    response_format={"type": "json_object"},  # Specify the response format as JSON.
)

# Extract and print the JSON result generated by the model.
json_string = completion.choices[0].message.content
print(json_string)

Response

{
  "info": {
    "name": "Alex Brown",
    "age": "34 years old",
    "email": "alexbrown@example.com"
  },
  "hobby": ["Basketball", "Traveling"]
}

Node.js

import OpenAI from "openai";

// Predefined example responses (to demonstrate the expected output format to the model)
// Example 1: Complete response containing all fields
const example1Response = JSON.stringify({
    info: { name: "Alice", age: "25 years old", email: "alice@example.com" },
    hobby: ["singing"]
}, null, 2);

// Example 2: Response containing multiple hobbies
const example2Response = JSON.stringify({
    info: { name: "Bob", age: "30 years old", email: "bob@example.com" },
    hobby: ["dancing", "swimming"]
}, null, 2);

// Example 3: Response without the hobby field (hobby is optional)
const example3Response = JSON.stringify({
    info: { name: "Dave", age: "28 years old", email: "dave@example.com" }
}, null, 2);

// Example 4: Another response without the hobby field
const example4Response = JSON.stringify({
    info: { name: "Sun Qi", age: "35 years old", email: "sunqi@example.com" }
}, null, 2);

// Initialize the OpenAI client configuration
const openai = new OpenAI({
    // If environment variables are not configured, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
    // API keys vary by region. To obtain an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    apiKey: process.env.DASHSCOPE_API_KEY,
    // The following is the base URL for the Beijing region. If you use a model in the Singapore region, replace the base URL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
});

// Create a chat completion request using a structured prompt to improve output accuracy
const completion = await openai.chat.completions.create({
    model: "qwen3.8-max",
    messages: [
        {
            role: "system",
            content: `Extract personal information from the user input and output it in the specified JSON Schema format:

Output format requirements
The output must strictly follow this JSON structure:
{
  "info": {
    "name": "String type, required field, user's name",
    "age": "String type, required field, formatted as 'number + years old', for example, '25 years old'",
    "email": "String type, required field, standard email format, for example, 'user@example.com'"
  },
  "hobby": ["String array type, optional field, contains all user hobbies; omit this field entirely if hobbies are not mentioned"]
}

Field extraction rules
1. name: Identify the user's name from the text; this field is required
2. age: Identify the age information and convert it to the 'number + years old' format; this field is required
3. email: Identify the email address and retain its original format; this field is required
4. hobby: Identify the user's hobbies and output them as a string array; omit the hobby field entirely if no hobbies are mentioned

Reference examples
Example 1 (with hobbies):
Q: My name is Alice, I am 25 years old, my email is alice@example.com, and my hobby is singing
A: ${example1Response}

Example 2 (with multiple hobbies):
Q: My name is Bob, I am 30 years old, my email is bob@example.com, and I enjoy dancing and swimming
A: ${example2Response}

Example 3 (without hobbies):
Q: My name is Dave, I am 28 years old, and my email is dave@example.com
A: ${example3Response}

Example 4 (without hobbies):
Q: I am Sun Qi, 35 years old, and my email is sunqi@example.com
A: ${example4Response}

Strictly follow the above format and rules to extract information and output JSON. If the user does not mention hobbies, do not include the hobby field in the output.`
        },
        {
            role: "user",
            content: "Hello everyone, my name is Alex Brown, I am 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling"
        }
    ],
    response_format: {
        type: "json_object"
    }
});

// Extract and print the JSON result generated by the model
const jsonString = completion.choices[0].message.content;
console.log(jsonString);

Response

{
  "info": {
    "name": "Alex Brown",
    "age": "34 years old",
    "email": "alexbrown@example.com"
  },
  "hobby": [
    "playing basketball",
    "traveling"
  ]
}

DashScope

Python

import os
import json
import dashscope

# The following configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# If you use Singapore region models, replace the region with ap-southeast-1
client = dashscope.Client(
    # If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API key: api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Predefined sample responses (to show the model the expected output format).
example1_response = json.dumps(
    {
        "info": {"name": "Alice", "age": "25 years old", "email": "alice@example.com"},
        "hobby": ["singing"]
    },
    ensure_ascii=False
)
example2_response = json.dumps(
    {
        "info": {"name": "Bob", "age": "30 years old", "email": "bob@example.com"},
        "hobby": ["dancing", "swimming"]
    },
    ensure_ascii=False
)
example3_response = json.dumps(
    {
        "info": {"name": "Charlie", "age": "40 years old", "email": "charlie@example.com"},
        "hobby": ["Rap", "basketball"]
    },
    ensure_ascii=False
)

messages=[
        {
            "role": "system",
            "content": f"""Please extract personal information from the user input and output it in the specified JSON Schema format:

[Output Format Requirements]
The output must strictly follow the JSON structure below:
{{
  "info": {{
    "name": "String type, required field, user's name",
    "age": "String type, required field, format is 'number years old', for example, '25 years old'",
    "email": "String type, required field, standard email format, for example, 'user@example.com'"
  }},
  "hobby": ["String array type, optional field, contains all of the user's hobbies. If not mentioned, this field should be completely omitted from the output."]
}}

[Field Extraction Rules]
1. name: Identify the user's name from the text. This is a required field.
2. age: Identify the age information and convert it to the 'number years old' format. This is a required field.
3. email: Identify the email address and keep its original format. This is a required field.
4. hobby: Identify the user's hobbies and output them as a string array. If no hobbies are mentioned, omit the hobby field entirely.

[Reference Examples]
Example 1 (includes a hobby):
Q: My name is Alice, I am 25 years old, my email is alice@example.com, and my hobby is singing.
A: {example1_response}

Example 2 (includes multiple hobbies):
Q: My name is Bob, I am 30 years old, my email is bob@example.com, and I like dancing and swimming.
A: {example2_response}

Example 3 (includes multiple hobbies):
Q: My email is charlie@example.com, I am 40 years old, my name is Charlie, and I can rap and play basketball.
A: {example3_response}

Please strictly follow the format and rules above to extract information and output it in JSON format. If the user does not mention any hobbies, do not include the hobby field in the output."""
        },
        {
            "role": "user",
            "content": [{"text": "Hello everyone, my name is Alex Brown, I am 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling."}],
        },
    ]
response = client.multimodal.chat.create(
    model="qwen3.8-max",
    messages=messages,
    response_format={'type': 'json_object'}
    )
json_string = response.choices[0].message.content
print(json_string)

Response

{
  "info": {
    "name": "Alex Brown",
    "age": "34 years old",
    "email": "alexbrown@example.com"
  },
  "hobby": [
    "playing basketball",
    "traveling"
  ]
}

Java

import java.util.Arrays;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.common.ResponseFormat;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    // To use models in the Singapore region, uncomment the following line
    // static {Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";}
    public static void simpleMultiModalConversationCall()
            throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("text", """
                Extract personal information from the user input and output it in the specified JSON Schema format:

[Output Format Requirements]
The output must strictly follow this JSON structure:
{
  "info": {
    "name": "String type. Required field. User's name.",
    "age": "String type. Required field. Format: 'number followed by years old', for example, '25 years old'.",
    "email": "String type. Required field. Standard mailbox format, for example, 'user@example.com'."
  },
  "hobby": ["Array of strings. Optional field. Contains all user hobbies. Omit this field entirely if not mentioned."]
}

[Field Extraction Rules]
1. name: Detect the user's name from the text. This field is required.
2. age: Detect age information and convert it to the format 'number followed by years old'. This field is required.
3. email: Detect the mailbox address and retain the original format. This field is required.
4. hobby: Detect user hobbies and output them as an array of strings. Omit the hobby field entirely if hobby information is not mentioned.

[Reference Examples]
Example 1 (with hobbies):
Q: Hello, my name is Alice, I am 25 years old, my mailbox is alice@example.com, and my hobby is singing.
A: {"info":{"name":"Alice","age":"25 years old","email":"alice@example.com"},"hobby":["singing"]}

Example 2 (with multiple hobbies):
Q: Hello, my name is Bob, I am 30 years old, my mailbox is bob@example.com, and I usually enjoy dancing and swimming.
A: {"info":{"name":"Bob","age":"30 years old","email":"bob@example.com"},"hobby":["dancing","swimming"]}

Example 3 (without hobbies):
Q: Hello, my name is Charlie, my mailbox is charlie@example.com, and I am 40 years old.
A: {"info":{"name":"Charlie","age":"40 years old","email":"charlie@example.com"}}"""))).build();
        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("text", "Hello, my name is Alex Brown, I am 34 years old, my mailbox is alexbrown@example.com, and I usually enjoy playing basketball and traveling."))).build();
        ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // If you have not configured an environment variable, replace the following line with: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen3.8-max")
                .messages(Arrays.asList(systemMessage, userMessage))
                .responseFormat(jsonMode)
                .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
    }
    public static void main(String[] args) {
        try {
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
    }
}

Response

{
  "info": {
    "name": "Alex Brown",
    "age": "34 years old",
    "email": "alexbrown@example.com"
  },
  "hobby": [
    "Playing basketball",
    "Traveling"
  ]
}

Getting structured output

Setting response_format type to json_object returns a valid JSON string, but the structure may not match your expectations - suitable for simple scenarios. For automated parsing, API interoperability, and other complex scenarios requiring strict type constraints, set type to json_schema to force the model to output content that strictly conforms to a specified format. The response_format format and example:

NoteMultimodal inputs (image, video, audio, etc.) do not support json_schema and will automatically fall back to json_object; the schema constraints will not take effect.

Format

{
  "type": "json_schema",
  "json_schema": {
    "name": "schema_name",       // Name of the schema
    "strict": true,              // Recommended: strictly follow the format
    "schema": {
      "type": "object",
      "properties": {...},       // Define field structure (see example on right)
      "required": [...],         // List of required fields
      "additionalProperties": false  // Recommended: only output defined fields
    }
  }
}

Example

{
  "type": "json_schema",
  "json_schema": {
    "name": "user_info",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "User name"
        },
        "age": {
          "type": "integer",
          "description": "User age"
        },
        "email": {
          "type": "string",
          "description": "Email address"
        }
      },
      "required": ["name", "age"],
      "additionalProperties": false
    }
  }
}

The example above forces the model to output a JSON object with two required fields (name and age) and an optional email field.

How to use

With the OpenAI SDK parse method, you can pass a Python Pydantic class or Node.js Zod object directly. The SDK automatically converts it to a JSON Schema - no need to write complex JSON manually. For the DashScope SDK, construct the JSON Schema manually following the format above.

OpenAI-compatible Chat Completions API

Python

from pydantic import BaseModel, Field
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
)

class UserInfo(BaseModel):
    name: str = Field(description="User name")
    age: int = Field(description="User age in years")

completion = client.chat.completions.parse(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "Extract name and age information."},
        {"role": "user", "content": "My name is Liu Wu, I'm 25 years old."},
    ],
    response_format=UserInfo,
)

result = completion.choices[0].message.parsed
print(f"Name: {result.name}, Age: {result.age}")

Node.js

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const openai = new OpenAI(
    {
        apiKey: process.env.DASHSCOPE_API_KEY,
        // The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
    }
);

const UserInfo = z.object({
  name: z.string().describe("User name"),
  age: z.number().int().describe("User age in years"),
});

const completion = await openai.chat.completions.parse({
  model: "qwen3.8-max",
  messages: [
    { role: "system", content: "Extract name and age information." },
    { role: "user", content: "My name is Liu Wu, I'm 25 years old." },
  ],
  response_format: zodResponseFormat(UserInfo, "user_info"),
});

const userInfo = completion.choices[0].message.parsed;
console.log(`Name: ${userInfo.name}`);
console.log(`Age: ${userInfo.age}`);

Running the code produces the following output:

Name: Liu Wu, Age: 25

OpenAI-Compatible Responses API

Responses API configures structured output with the text.format parameter, which supports the json_schema and json_object types. The OpenAI SDK parse method also works here: pass a Pydantic class or Zod object to text_format.

from pydantic import BaseModel, Field
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
)

class UserInfo(BaseModel):
    name: str = Field(description="User name")
    age: int = Field(description="User age in years")

response = client.responses.parse(
    model="qwen3.8-max",
    input="My name is Liu Wu, I'm 25 years old.",
    text_format=UserInfo,
)

result = response.output_parsed
print(f"Name: {result.name}, Age: {result.age}")

Running the code produces the following output:

Name: Liu Wu, Age: 25

For parameter details, see the text parameter of the Responses API.

DashScope API

Java SDK is not supported yet.

import os
import dashscope
import json

# The following configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

messages = [
    {
        "role": "user",
        "content": [{"text": "My name is Liu Wu, I'm 25 years old."}],
    },
]
response = client.multimodal.chat.create(
    model="qwen3.8-max",
    messages=messages,
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "user_info",
            "strict": True,
            "schema": {
                "properties": {
                    "name": {"title": "Name", "type": "string"},
                    "age": {"title": "Age", "type": "integer"},
                },
                "required": ["name", "age"],
                "title": "UserInfo",
                "type": "object",
            },
        },
    },
)
json_object = json.loads(response.choices[0].message.content)
print(f"Name: {json_object['name']}, Age: {json_object['age']}")

Running the code produces the following output:

Name: Liu Wu, Age: 25

Configuration guide

Follow these guidelines when using JSON Schema for more reliable structured output:

Required field declaration
It is recommended to list required fields in the required array. Optional fields can be omitted, for example:

{
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"},
    "email": {"type": "string"}
  },
  "required": ["name", "age"]
}

If the input does not provide email information, the output will not contain this field.

Implementing optional fields
Besides omitting from required, you can also allow the null type:

{
  "properties": {
    "name": {"type": "string"},
    "email": {"type": ["string", "null"]}  // Can be string or null
  },
  "required": ["name", "email"]  // Both in required
}

The output will always include the email field, but its value may be null.

additionalProperties configuration
Controls whether to allow extra fields not defined in the schema:

{
  "properties": {"name": {"type": "string"}},
  "required": ["name"],
  "additionalProperties": true  // Allow extra fields
}

Example input: "I'm Zhang San, 25 years old"; output: {"name": "Zhang San", "age": 25} (includes the undefined age field).

Value	Behavior	Use case
`false`	Only output defined fields	Precise structure control
`true`	Allow extra fields	Capture more information

Supported JSON Schema keywords

The following lists the keywords supported by JSON Schema mode (strict mode). Keywords marked as "unsupported" return a 400 error when submitted. For the complete keyword definitions, see the JSON Schema specification.

Schema-level common keywords

Keyword	Description
`type`	Supports `string`, `number`, `integer`, `boolean`, `null`, `array`, `object`; union types such as `["string", "null"]` are also supported
`enum` / `const`	`enum` restricts the value to a set of allowed values; `const` restricts it to a single fixed value
`$defs` + `$ref`	Local references are supported (e.g., `#/$defs/address`); external URL references do not cause errors but have no effect
`anyOf` / `oneOf` / `allOf` / `not`	Composition and conditional constraints are supported. Note that `oneOf` does not strictly guarantee exactly-one semantics
`if` / `then` / `else`	Conditional schemas are supported, enabling dynamic validation rules based on field values
`title` / `description` / `default` / `examples`	Accepted as semantic hints for the model; not enforced as hard constraints
`$schema` / `$id` / `$comment`	Meta identifiers; accepted without affecting validation behavior
`deprecated` / `readOnly` / `writeOnly`	Annotation keywords; accepted without affecting validation behavior

Type-specific keywords

Type	Supported keywords	Unsupported keywords (400 error)
`string`	`minLength`, `maxLength`, `pattern`, `format` (e.g., `email`, `date`), `contentMediaType`, `contentEncoding`	-
`number` / `integer`	`minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`	`multipleOf`
`array`	`items`, `prefixItems` (tuple mode), `minItems`, `maxItems`, `unevaluatedItems`	`uniqueItems`, `contains`, `minContains`, `maxContains`, `additionalItems`
`object`	`properties`, `required`, `additionalProperties`, `minProperties`, `maxProperties`, `dependentRequired`, `dependentSchemas`, `unevaluatedProperties`	`patternProperties`, `propertyNames`

Going live

Validate before passing downstream
When using JSON Object mode, validate the output before passing it to downstream services. Use a library such as jsonschema (Python), Ajv (JavaScript), or Everit (Java) to ensure it conforms to the expected JSON Schema, preventing downstream parsing failures, data loss, or business logic disruptions due to missing fields, type errors, or malformed formats. On failure, retry the request or use a model to rewrite the output.
Do not set max_tokens
Do not set max_tokens when structured output is enabled. This parameter caps the number of output tokens and defaults to the model's maximum. Setting it may truncate the JSON string mid-output, producing invalid JSON that fails to parse.

Use SDK to generate schemas

Use the SDK to auto-generate schemas. This avoids errors from manual maintenance and provides automatic validation and parsing.

Python

from pydantic import BaseModel, Field
from typing import Optional
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
)
class UserInfo(BaseModel):
    name: str = Field(description="User name")
    age: int = Field(description="User age")
    email: Optional[str] = None  # Optional field

completion = client.chat.completions.parse(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "Extract name and age information."},
        {"role": "user", "content": "My name is Liu Wu, I'm 25 years old."},
    ],
    response_format=UserInfo  # Pass the Pydantic model directly
)

result = completion.choices[0].message.parsed  # Type-safe parsed result
print(f"Name: {result.name}, Age: {result.age}")

Node.js

import { z } from "zod";
import { zodResponseFormat } from "openai/helpers/zod";
import OpenAI from "openai";

const client = new OpenAI(
    {
        apiKey: process.env.DASHSCOPE_API_KEY,
        // The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
    }
);

const UserInfo = z.object({
  name: z.string().describe("User name"),
  age: z.number().int().describe("User age"),
  email: z.string().optional().nullable()  // Optional field
});

const completion = await client.chat.completions.parse({
  model: "qwen3.8-max",
  messages: [
    { role: "system", content: "Extract name and age information." },
    { role: "user", content: "My name is Liu Wu, I'm 25 years old." },
  ],
  response_format: zodResponseFormat(UserInfo, "user_info")
});

console.log(completion.choices[0].message.parsed);

Error codes

If the model call fails and returns an error message, see Error codes for resolution.