Skip to main content
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Text generation

Structured output

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.
Feature comparison:

Feature

JSON Object mode

JSON Schema mode

Outputs valid JSON

Yes

Yes

Strictly follows schema

No

Yes

Supported models

Most Qwen models

Only selected qwen-plus 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

  • JSON Object
  • JSON Schema
  • Qwen
  • Kimi
  • GLM
  • DeepSeek
  • 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.5-Omni-Plus series
    • Qwen3-VL open-source series (non-thinking mode)
Models labeled "non-thinking mode" also accept response_format set to {"type": "json_object"} in thinking mode without error, but some may return content that is not strictly valid JSON; if you need reliably valid JSON, see the FAQ.

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
  • DashScope
  • Python
  • Node.js
  • curl
from openai import OpenAI
import os

client = OpenAI(
    # API keys differ by region. If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # If you use Beijing region models, replace base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.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
}

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
  • DashScope
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # API keys differ by region. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # For Beijing region models, replace base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

completion = client.chat.completions.create(
    model="qwen3-vl-plus",
    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"
    }
  ]
}

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
  • DashScope
  • Python
  • Node.js
from openai import OpenAI
import os
import json
import textwrap  # Handles indentation for multi-line strings to improve code readability

# Predefined example responses to show the model the expected output format
# Example 1: Complete response with all fields
example1_response = json.dumps(
    {
        "info": {"name": "Alice", "age": "25 years old", "email": "alice@example.com"},
        "hobby": ["singing"]
    },
    ensure_ascii=False
)
# Example 2: Response with multiple hobbies
example2_response = json.dumps(
    {
        "info": {"name": "Bob", "age": "30 years old", "email": "bob@example.com"},
        "hobby": ["dancing", "swimming"]
    },
    ensure_ascii=False
)
# Example 3: Response without hobby field (hobby is optional)
example3_response = json.dumps(
    {
        "info": {"name": "Dave", "age": "28 years old", "email": "dave@example.com"}
    },
    ensure_ascii=False
)
# Example 4: Another response without hobby field
example4_response = json.dumps(
    {
        "info": {"name": "Sun Qi", "age": "35 years old", "email": "sunqi@example.com"}
    },
    ensure_ascii=False
)

# Initialize the OpenAI client
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://www.alibabacloud.com/help/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",
)

# dedent removes common leading whitespace from each line, allowing the string to be indented nicely in code without including extra spaces at runtime
system_prompt = textwrap.dedent(f"""\
    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 years old', e.g., '25 years old'",
        "email": "string type, required field, standard email format, e.g., 'user@example.com'"
      }},
      "hobby": ["string array type, optional field, contains all user hobbies; omit entirely if not mentioned"]
    }}

    [Field extraction rules]
    1. name: Identify the user's name from the text, must extract
    2. age: Identify age information, convert to 'number years old' format, must extract
    3. email: Identify email address, keep original format, must extract
    4. hobby: Identify user hobbies, output as string array; omit hobby field entirely if hobbies are not mentioned

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

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

    Example 3 (without hobby):
    Q: My name is Dave, I'm 28 years old, and my email is dave@example.com
    A: {example3_response}

    Example 4 (without hobby):
    Q: I'm Sun Qi, 35 years old, and my email is sunqi@example.com
    A: {example4_response}

    Extract information and output JSON strictly according to the above format and rules. Do not include the hobby field if the user doesn't mention hobbies.\
""")

# Call the model API for information extraction
completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "system",
            "content": system_prompt
        },
        {
            "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"},  # Specify JSON format return
)

# Extract and print the model-generated JSON result
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"]
}

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: 
{
  "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
    }
  }
}
The example above forces the model to output a JSON object with two required fields (name and age) and an optional email field.
Singapore region models are not supported yet.

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
  • DashScope

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 Singapore region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.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 Singapore region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.ap-southeast-1.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

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 data types: string, number, integer, boolean, object, array, enum.

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 Singapore region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.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}")

FAQ

Q: How does Qwen's thinking mode model produce structured output?

Models labeled "non-thinking mode" returns content that is not a strictly valid JSON string in thinking mode, you can use the following two-step approach to fix it: first call the thinking model to get high-quality output, then pass any malformed JSON through a model that supports JSON mode to fix it.
  1. Get output from the thinking mode model Call the thinking mode model. The result may not be valid JSON.
    Note: setting the response_format parameter to {"type": "json_object"} when thinking mode is enabled does not cause an error. The following is a fallback example that intentionally omits response_format; use it only to fix cases where a model's output is not valid JSON. 
completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": system_prompt},
        {
            "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",
        },
    ],
    # Enable thinking mode; this fallback example omits the response_format parameter (setting it directly does not cause an error)
    extra_body={"enable_thinking": True},
    # Streaming output is required in thinking mode
    stream=True
)
# Extract and print the model-generated JSON result
json_string = ""
for chunk in completion:
    if not chunk.choices:
        continue
    if chunk.choices[0].delta.content is not None:
        json_string += chunk.choices[0].delta.content
  1. Validate and fix the output Try to parse the json_string from the previous step:
    • If the model returned valid JSON, parse and use it directly.
    • If the model returned invalid JSON, call a model that supports structured output (a fast, low-cost model such as qwen-flash in non-thinking mode works well) to fix the format.
import json
from openai import OpenAI
import os

# Initialize the OpenAI client (if the client variable isn't defined in the previous code block, uncomment the lines below)
# client = OpenAI(
#     api_key=os.getenv("DASHSCOPE_API_KEY"),
#     base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
# )

try:
    json_object_from_thinking_model = json.loads(json_string)
    print("Generated standard JSON string")
except json.JSONDecodeError:
    print("Did not generate standard JSON string; fixing with a model that supports structured output")
    completion = client.chat.completions.create(
        model="qwen-flash",
        # Use non-thinking mode
        extra_body={"enable_thinking": False},
        messages=[
            {
                "role": "system",
                "content": "You are a JSON format expert. Fix the user's JSON string to standard format",
            },
            {
                "role": "user",
                "content": json_string,
            },
        ],
        response_format={"type": "json_object"},
    )
    json_object_from_thinking_model = json.loads(completion.choices[0].message.content)

Error codes

If the model call fails and returns an error message, see Error codes for resolution.
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Get Started
Billing
Token Plan
Model Playground
Clients and Developer Tools
Model Inference
Fine-tuning
Deployment
Evaluation
Statistics and Monitoring
Security and Compliance
Best Practices
Support
Changelog
Structured output - Alibaba Cloud Model Studio