All Products
Search
Document Center

Alibaba Cloud Model Studio:JSON mode

Last Updated:Apr 08, 2025

In information extraction scenarios, you can prompt the model to generate standard JSON strings. However, model responses can be unpredictable and may not conform to JSON format. For example, the response may include ```json``` or phrases like "The following is a JSON string," which complicates subsequent parsing. The structured output feature ensures consistent production of standard JSON strings by the model.

Supported models

The structured output feature supports the following models:

  • Qwen-Max

    qwen-max, qwen-max-latest, qwen-max-0125

  • Qwen-Plus

    qwen-plus, qwen-plus-latest, qwen-plus-0125

  • Qwen-Turbo

    qwen-turbo, qwen-turbo-latest, qwen-turbo-1101

  • Open source Qwen

    qwen2.5 models

Get started

Prerequisites

You must have obtained an API key and set it as an environment variable. If you need to use the OpenAI SDK or DashScope SDK, you must install the appropriate SDK.

How to use

Your request must satisfy two conditions:

  • Set the Parameter

    Set the request parameter response_format to {"type": "json_object"}.

  • Guide in Prompt

    Guide the model to output JSON strings in the prompt. Otherwise, an error will occur: 'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.

We recommend that you specify the data type for each property in the prompt and provide examples for the model to reference.

OpenAI compatible

Python

Sample code

# Import required libraries
from openai import OpenAI
import os
import json

# Predefined example responses (for few-shot prompting)
example1_response = json.dumps(
    {
        "info": {"name": "Alice", "age": "25", "email": "alice@example.com"},
        "hobby": ["Singing"]
    },
    ensure_ascii=False
)
example2_response = json.dumps(
    {
        "info": {"name": "Bob", "age": "30", "email": "bob@example.com"},
        "hobby": ["Dancing", "Swimming"]
    },
    ensure_ascii=False
)
example3_response = json.dumps(
    {
        "info": {"name": "Charlie", "age": "40", "email": "charlie@example.com"},
        "hobby": ["Rap", "Basketball"]
    },
    ensure_ascii=False
)

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {
            "role": "system",
            "content": f"""Extract name, age, email, and hobby (array type), and output JSON containing the info layer and hobby array.
            Example:
            Q: My name is Alice, I am 25 years old, my email is alice@example.com, and my hobby is singing
            A: {example1_response}
            
            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}
            
            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}"""
        },
        {
            "role": "user",
            "content": "Hello everyone, my name is Dave, I am 34 years old, my email is dave@example.com, and I like playing basketball and traveling", 
        },
    ],
    response_format={"type": "json_object"},
)

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

Sample response

{"info": {"name": "Dave", "age": "34", "email": "dave@example.com"}, "hobby": ["Basketball", "Traveling"]}

Node.js

Sample code

// Step 1: Send request

import OpenAI from "openai";

// Predefined example responses
const example1Response = JSON.stringify({
    info: { name: "Alice", age: "25", email: "alice@example.com" },
    hobby: ["Singing"]
});
const example2Response = JSON.stringify({
    info: { name: "Bob", age: "30", email: "bob@example.com" },
    hobby: ["Dancing", "Swimming"]
});
const example3Response = JSON.stringify({
    info: { name: "Charlie", age: "40", email: "charlie@example.com" },
    hobby: ["Rap", "Basketball"]
});

const openai = new OpenAI({
    // If the environment variable is not configured, replace the following line with: apiKey: "sk-xxx",
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
});

const completion = await openai.chat.completions.create({
    model: "qwen-plus",
    messages: [
        {
            role: "system",
            content: `Extract name, age, email, and hobby (array type), and output JSON containing the info layer and hobby array.
            Example:
            Q: My name is Alice, I am 25 years old, my email is alice@example.com, and my hobby is singing
            A: ${example1Response}
            
            Q: My name is Bob, I am 30 years old, my email is bob@example.com, and I like dancing and swimming
            A: ${example2Response}
            
            Q: My email is charlie@example.com, I am 40 years old, my name is Charlie, and I can rap and play basketball
            A: ${example3Response}`
        },
        {
            role: "user",
            content: "Hello everyone, my name is Dave, I am 34 years old, my email is dave@example.com, and I like playing basketball and traveling"
        }
    ],
    response_format: {
        type: "json_object"
    }
});

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

Sample response

{"info":{"name":"Dave","age":"34","email":"dave@example.com"},"hobby":["Basketball","Traveling"]}

cURL

Sample request

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "You need to extract the name (as a string), age (as a string), and email (as a string), and output a JSON string without any other irrelevant content.\nExample:\nQ: My name is Alice, I am 25 years old, and my email is alice@example.com\nA: {\"name\":\"Alice\",\"age\":\"25\",\"email\":\"alice@example.com\"}\nQ: My name is Bob, I am 30 years old, and my email is bob@example.com\nA: {\"name\":\"Bob\",\"age\":\"30\",\"email\":\"bob@example.com\"}\nQ: My name is Charlie, my email is charlie@example.com, and I am 40 years old\nA: {\"name\":\"Charlie\",\"age\":\"40\",\"email\":\"charlie@example.com\""
        },
        {
            "role": "user", 
            "content": "Hello everyone, my name is Dave, I am 34 years old, and my email is dave@example.com"
        }
    ],
    "response_format": {
        "type": "json_object"
    }
}'

Sample response

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "{\n  \"name\": \"Alice\",\n  \"age\": 25,\n  \"email\": \"alice@example.com\"\n}"
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 65,
        "completion_tokens": 29,
        "total_tokens": 94,
        "prompt_tokens_details": {
            "cached_tokens": 0
        }
    },
    "created": 1736771145,
    "system_fingerprint": null,
    "model": "qwen-plus",
    "id": "chatcmpl-59b28c8b-6cb7-9e4d-9a78-3cbed664d3c0"
}

DashScope

Python

Sample code

# Step 1: Send request

import os
import json
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Predefined example responses (for few-shot prompting)
example1_response = json.dumps(
    {
        "info": {"name": "Alice", "age": "25", "email": "alice@example.com"},
        "hobby": ["Singing"]
    },
    ensure_ascii=False
)
example2_response = json.dumps(
    {
        "info": {"name": "Bob", "age": "30", "email": "bob@example.com"},
        "hobby": ["Dancing", "Swimming"]
    },
    ensure_ascii=False
)
example3_response = json.dumps(
    {
        "info": {"name": "Charlie", "age": "40", "email": "charlie@example.com"},
        "hobby": ["Rap", "Basketball"]
    },
    ensure_ascii=False
)

messages=[
        {
            "role": "system",
            "content": f"""Extract name, age, email, and hobby (array type), and output JSON containing the info layer and hobby array.
            Example:
            Q: My name is Alice, I am 25 years old, my email is alice@example.com, and my hobby is singing
            A: {example1_response}
            
            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}
            
            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}"""
        },
        {
            "role": "user",
            "content": "Hello everyone, my name is Dave, I am 34 years old, my email is dave@example.com, and I like playing basketball and traveling", 
        },
    ]
response = dashscope.Generation.call(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-plus", 
    messages=messages,
    result_format='message',
    response_format={'type': 'json_object'}
    )
json_string = response.output.choices[0].message.content
print(json_string)

Sample response

{"info": {"name": "Dave", "age": "34", "email": "dave@example.com"}, "hobby": ["Basketball", "Traveling"]}

Java

import java.util.Arrays;
import java.lang.System;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.common.ResponseFormat;
import com.alibaba.dashscope.protocol.Protocol;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("""
                You need to extract the name (as a string), age (as a string), and email (as a string), and output a JSON string without any other irrelevant content.
                Example:
                Q: My name is Alice, I am 25 years old, my email is alice@example.com
                A: {"name":"Alice","age":"25","email":"alice@example.com"}
                Q: My name is Bob, I am 30 years old, my email is bob@example.com
                A: {"name":"Bob","age":"30","email":"bob@example.com"}
                Q: My name is Charlie, my email is charlie@example.com, and I am 40 years old
                A: {"name":"Charlie","age":"40","email":"charlie@example.com"}""")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("Hello everyone, my name is Dave, I am 34 years old, and my email is dave@example.com")
                .build();
        ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
        GenerationParam param = GenerationParam.builder()
                // If environment variables are not configured, please replace the following line with the Baolian API Key: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // Here we use qwen-plus as an example, you can change the model name as needed. Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
                .model("qwen-plus")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .responseFormat(jsonMode)
                .build();
        return gen.call(param);
    }
    public static void main(String[] args) {
        try {
            GenerationResult result = callWithMessage();
            System.out.println(JsonUtils.toJson(result));
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // Use logging framework to record exception information
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
        System.exit(0);
    }
}

cURL

Sample code

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "input": {
        "messages": [
            {
                "role": "system",
                "content": "You need to extract the name (as a string), age (as a string), and email (as a string), and output a JSON string without any other irrelevant content.\nExample:\nQ: My name is Alice, I am 25 years old, and my email is alice@example.com\nA: {\"name\":\"Alice\",\"age\":\"25\",\"email\":\"alice@example.com\"}\nQ: My name is Bob, I am 30 years old, and my email is bob@example.com\nA: {\"name\":\"Bob\",\"age\":\"30\",\"email\":\"bob@example.com\"}\nQ: My name is Charlie, my email is charlie@example.com, and I am 40 years old\nA: {\"name\":\"Charlie\",\"age\":\"40\",\"email\":\"charlie@example.com\""
            },
            {
                "role": "user", 
                "content": "Hello everyone, my name is Dave, I am 34 years old, and my email is dave@example.com"
            }
        ]
    },
    "parameters": {
        "result_format": "message",
        "response_format": {
            "type": "json_object"
        }
    }
}'

Sample response

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "{\"name\":\"Dave\",\"age\":\"34\",\"email\":\"dave@example.com\"}"
                }
            }
        ]
    },
    "usage": {
        "prompt_tokens_details": {
            "cached_tokens": 0
        },
        "total_tokens": 223,
        "output_tokens": 20,
        "input_tokens": 203
    },
    "request_id": "0c353885-ffdc-9b99-a273-ade7b14f3fab"
}

Parse JSON strings

Once you have the JSON string generated by the model, you can parse it with JSON tools.

# Step 2: Parse the JSON string. Add the following code after Step 1
import json
json_object = json.loads(json_string)
print(json_object)
// Step 2: Parse the JSON string. Add the following code after Step 1
const jsonObject = JSON.parse(jsonString);
console.log(jsonObject);
// JSON dependency is required
import org.json.JSONObject;

...

String jsonString = result.getOutput().getChoices().get(0).getMessage().getContent();
JSONObject jsonObject = new JSONObject(jsonString);
System.out.println(jsonObject);

The code converts the JSON string into a JSON object.

FAQ

Q: Does the Qwen API support generating data based on the JSON schema I provide?

A: The Qwen API can only validate JSON strings based on the prompts you enter. It does not support data generation based on a provided JSON Schema.

To achieve a similar outcome, you can precisely outline the required key-value structure and data types in the prompt, and offer standard data samples for reference.

Error code

If the call failed and an error message is returned, see Error messages.