All Products
Search

This Product

    Alibaba Cloud Model Studio:OpenAI compatible - Conversations

    Document Center

    Alibaba Cloud Model Studio:OpenAI compatible - Conversations

    Last Updated:Mar 05, 2026

    Manually managing message lists for conversations that span multiple devices or have long interruptions can lead to context loss. Alibaba Cloud Model Studio provides an OpenAI compatible Conversations API that you can use with the Responses API to automatically inject historical context. This eliminates the need for manual message synchronization and ensures conversational continuity across different scenarios and devices.

    Create conversation

    Creates a new conversation. You can optionally include initial message items.

    Chinese mainland: POST https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations

    International: POST https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations

    items array (Optional)

    A list of up to 20 initial message items.

    Properties

    type string (Required)

    The message type. Only message is supported.

    role string (Required)

    The role of the message. Instructions from the system and developer roles have a higher priority than instructions from the user role. The assistant role indicates messages that were generated by the model in previous interactions. Valid values are user, assistant, system, and developer.

    content string or array (Required)

    The message content. This parameter supports plain text strings or structured content lists, such as ResponseInputText object arrays. The list format can include various content types, such as text.

    Python

    import os
from openai import OpenAI

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

conversation = client.conversations.create(
    metadata={"topic": "demo"},
    items=[
        {"type": "message", "role": "system", "content": "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess."}
    ]
)
print(conversation)

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const conversation = await client.conversations.create({
    metadata: { topic: "demo" },
    items: [
        {
            type: "message",
            role: "system",
            content: "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess."
        }
    ]
});
console.log(conversation);

    cURL

    curl --location 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
--data '{
    "metadata": {
        "topic": "demo"
    },
    "items": [
        {
            "type": "message",
            "role": "system",
            "content": "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess."
        }
    ]
}'

    metadata object (Optional)

    The conversation metadata. Use this parameter to store additional conversation information in a structured format. Specify up to 16 key-value pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.

    Response parameters

    created_at integer

    The Unix timestamp in milliseconds that indicates when the conversation was created.

    		 
    {
    "created_at": 1771316949128,
    "id": "conv_xxx",
    "metadata": {
        "topic": "demo"
    },
    "object": "conversation"
}

    id string

    The unique ID of the conversation.

    metadata object

    The conversation metadata. This parameter stores additional information as key-value pairs. It can contain up to 16 pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.

    object string

    The object type. The value is fixed as conversation.

    Retrieve conversation

    Retrieves information for a specified conversation.

    Chinese mainland: GET https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}

    International: GET https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}

    conversation_id string (Required, Path)

    The conversation ID.

    Python

    import os
from openai import OpenAI

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

conversation = client.conversations.retrieve("conv_xxx")
print(conversation)

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const conversation = await client.conversations.retrieve(
    "conv_xxx"
);
console.log(conversation);

    cURL

    curl --location 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/conv_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

    Response parameters

    created_at integer

    The Unix timestamp in milliseconds that indicates when the conversation was created.

    		 
    {
    "created_at": 1771316949128,
    "id": "conv_xxx",
    "metadata": {
        "topic": "demo"
    },
    "object": "conversation"
}

    id string

    The unique ID of the conversation.

    metadata object

    The conversation metadata. This parameter stores additional information as key-value pairs. It can contain up to 16 pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.

    object string

    The object type. The value is fixed as conversation.

    Update conversation

    Updates the metadata for a conversation.

    Chinese mainland: POST https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}

    International: POST https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}

    conversation_id string (Required, Path)

    The ID of the conversation.

    Python

    import os
from openai import OpenAI

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

updated = client.conversations.update(
    "conv_xxx",
    metadata={"topic": "update"}
)
print(updated)

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const updated = await client.conversations.update(
    "conv_xxx",
    { metadata: { topic: "update" } }
);
console.log(updated);

    cURL

    curl --location 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/conv_xxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
--data '{
    "metadata": {
        "topic": "update"
    }
}'

    metadata object (Required)

    The conversation metadata. This parameter completely overwrites the existing metadata. Specify up to 16 key-value pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.

    Response parameters

    created_at integer

    The Unix timestamp in milliseconds that indicates when the conversation was created.

    		 
    {
    "created_at": 1771318152759,
    "id": "conv_xxx",
    "metadata": {
        "topic": "update"
    },
    "object": "conversation"
}

    id string

    The unique ID of the conversation.

    metadata object

    The conversation metadata. This parameter stores additional information as key-value pairs. It can contain up to 16 pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.

    object string

    The object type. The value is fixed as conversation.

    Delete conversation

    Deletes a specified conversation. Message items within the conversation are not deleted.

    Chinese mainland: DELETE https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}

    International: DELETE https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}

    conversation_id string (Required, Path)

    The conversation ID.

    Python

    import os
from openai import OpenAI

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

result = client.conversations.delete("conv_xxx")
print(result)

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const result = await client.conversations.del(
    "conv_xxx"
);
console.log(result);

    cURL

    curl --location --request DELETE 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/conv_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

    Response parameters

    deleted boolean

    Indicates whether the deletion was successful.

    		 
    {
    "deleted": true,
    "id": "conv_xxx",
    "object": "conversation.deleted"
}

    id string

    The ID of the deleted conversation.

    object string

    The object type. The value is fixed as conversation.deleted.

    Create items

    Adds message items to a specified conversation.

    Chinese mainland: POST https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}/items

    International: POST https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}/items

    conversation_id string (Required, Path)

    The ID of the conversation.

    Python

    import os
from openai import OpenAI

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

items = client.conversations.items.create(
    "conv_xxx",
    items=[
        {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "Alice's major is teacher education"}],
        }
    ],
)
print(items.data)

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const items = await client.conversations.items.create(
    "conv_xxx",
    {
        items: [
            {
                type: "message",
                role: "user",
                content: [{ type: "input_text", text: "Alice's major is teacher education" }]
            }
        ]
    }
);
console.log(items.data);

    cURL

    curl --location 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/conv_xxx/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
--data '{
    "items": [
        {
            "type": "message",
            "role": "user",
            "content": [{
                "type": "input_text",
                "text": "Alice's major is teacher education"
            }]
        }
    ]
}'

    items array (Required)

    A list of message items. You can add up to 20 items at a time.

    Properties

    type string (Required)

    The message type. Only message is supported.

    role string (Required)

    The role of the message. Instructions from the system and developer roles have a higher priority than instructions from the user role. The assistant role indicates messages that were generated by the model in previous interactions. Valid values are user, assistant, system, and developer.

    content string or array (Required)

    The message content. This parameter supports plain text strings or structured content lists, such as ResponseInputText object arrays. The list format can include various content types, such as text.

    Response parameters

    data array[object]

    A list of the created message items.

    Properties

    id string

    The unique ID of the message item.

    content string or array

    The message content. This can be a plain text string or a structured content list, such as a ResponseInputText object array.

    role string

    The role of the message. Valid values are user, assistant, system, and developer.

    status string

    The processing status of the message. Valid values are in_progress, completed, and incomplete.

    type string

    The type of the message item. The value is fixed as message.

    		 
    {
    "data": [
        {
            "content": [
                {
                    "text": "Alice's major is teacher education",
                    "type": "input_text"
                }
            ],
            "id": "msg_xxx",
            "role": "user",
            "status": "completed",
            "type": "message"
        }
    ],
    "first_id": "msg_xxx",
    "has_more": false,
    "last_id": "msg_xxx"
}

    first_id string

    The ID of the first message item in the list.

    has_more boolean

    Indicates whether more data is available.

    last_id string

    The ID of the last message item in the list.

    List items

    Lists all message items in a conversation.

    Chinese mainland: GET https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}/items

    International: GET https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}/items

    conversation_id string (Required, Path)

    The ID of the conversation.

    Python

    import os
from openai import OpenAI

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

items = client.conversations.items.list("conv_xxx")
print(items.data)

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const items = await client.conversations.items.list(
    "conv_xxx"
);
console.log(items.data);

    cURL

    curl --location 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/conv_xxx/items?limit=10&order=asc' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

    after string (Optional)

    The pagination cursor. Returns only message items created after the specified message ID.

    order string (Optional)

    The sort order. Valid values are asc for ascending and desc for descending. The default value is desc.

    limit integer (Optional)

    The number of items to return. The value must be an integer from 1 to 100. The default value is 20.

    Response parameters

    data array[object]

    A list of the message items.

    Properties

    id string

    The unique ID of the message item.

    content string or array

    The message content. This can be a plain text string or a structured content list, such as a ResponseInputText object array.

    role string

    The role of the message. Valid values are user, assistant, system, and developer.

    status string

    The processing status of the message. Valid values are in_progress, completed, and incomplete.

    type string

    The type of the message item. The value is fixed as message.

    		 
    {
    "data": [
        {
            "content": [
                {
                    "text": "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess.",
                    "type": "input_text"
                }
            ],
            "id": "msg_7639f8f6-484b-454a-8125-96a3f40eb9e8",
            "role": "user",
            "status": "completed",
            "type": "message"
        },
        {
            "content": [
                {
                    "text": "Alice's best friend is Bob",
                    "type": "input_text"
                }
            ],
            "id": "msg_288594f6-6ef1-4519-94d4-a545ca311828",
            "role": "user",
            "status": "completed",
            "type": "message"
        }
    ],
    "first_id": "msg_7639f8f6-484b-454a-8125-96a3f40eb9e8",
    "has_more": false,
    "last_id": "msg_288594f6-6ef1-4519-94d4-a545ca311828",
    "object": "list"
}

    first_id string

    The ID of the first message item in the list.

    has_more boolean

    Indicates whether more data is available.

    last_id string

    The ID of the last message item in the list.

    object string

    The object type. The value is fixed as list.

    Retrieve item

    Retrieves the details for a specified message item.

    Chinese mainland: GET https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

    International: GET https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

    conversation_id string (Required, Path)

    The ID of the conversation.

    Python

    import os
from openai import OpenAI

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

item = client.conversations.items.retrieve(
    "msg_xxx",
    conversation_id="conv_xxx"
)
print(item)

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const item = await client.conversations.items.retrieve(
    "msg_xxx",
    { conversation_id: "conv_xxx" }
);
console.log(item);

    cURL

    curl --location 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/conv_xxx/items/msg_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

    item_id string (Required, Path)

    The ID of the message item.

    Response parameters

    content array[object]

    A list of message content that contains one or more content objects.

    Properties

    type string

    The content type, such as input_text for user input text or output_text for model output text.

    text string

    The text content.

    		 
    {
    "content": [
        {
            "text": "Alice's major is teacher education",
            "type": "input_text"
        }
    ],
    "id": "msg_xxx",
    "role": "user",
    "status": "completed",
    "type": "message"
}

    id string

    The unique ID of the message item.

    role string

    The role of the message. Valid values are user, assistant, system, and developer.

    status string

    The processing status of the message. Valid values are in_progress, completed, and incomplete.

    type string

    The type of the message item. The value is fixed as message.

    Delete item

    Deletes a specified message item.

    Chinese mainland: DELETE https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

    International: DELETE https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

    conversation_id string (Required, Path)

    The ID of the conversation.

    Python

    import os
from openai import OpenAI

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

result = client.conversations.items.delete(
    "msg_xxx",
    conversation_id="conv_xxx"
)
print(result)

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const result = await client.conversations.items.del(
    "msg_xxx",
    { conversation_id: "conv_xxx" }
);
console.log(result);

    cURL

    curl --location --request DELETE 'https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/conversations/conv_xxx/items/msg_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

    item_id string (Required, Path)

    The ID of the message item.

    Response parameters

    deleted boolean

    Indicates whether the item was successfully deleted.

    		 
    {
    "deleted": true,
    "id": "msg_xxx",
    "object": "conversation.item.deleted"
}

    id string

    The ID of the deleted message item.

    object string

    The object type. The value is fixed as conversation.item.deleted.

    Use conversations in the Responses API

    Use the conversation parameter of the Responses API to maintain context in multi-turn conversations.

    Do not pass both previous_response_id and conversation at the same time. Otherwise, the following error occurs: [400] INVALID_REQUEST: Mutually exclusive parameters: Ensure you are only providing one of: previous_response_id or conversation.

    Python

    import os
from openai import OpenAI

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

conversation = client.conversations.create(
    items=[
        {
            "type": "message",
            "role": "system",
            "content": "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess.",
        }
    ]
)

response1 = client.responses.create(
    conversation=conversation.id, model="qwen3.5-plus", input="How old is Alice?"
)
print(f"First response: {response1.output_text}")

response2 = client.responses.create(
    conversation=conversation.id, model="qwen3.5-plus", input="What are her hobbies?"
)
print(f"Second response: {response2.output_text}")

    Node.js

    import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
});

const conversation = await client.conversations.create({
  items: [
    {
      type: "message",
      role: "system",
      content: "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess."
    }
  ]
});

const response1 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.5-plus",
  input: "How old is Alice?"
});
console.log("First response:", response1.output_text);

const response2 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.5-plus",
  input: "What are her hobbies?"
});
console.log("Second response:", response2.output_text);

    Limitations

    • When you create a conversation or add message items, the items array can contain up to 20 entries.

    • The metadata object can contain up to 16 key-value pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.