DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio API Reference (Models) Toolkit/Framework OpenAI-compatible - Conversations

OpenAI-compatible - Conversations

Updated at:
Copy as MD
Product
My Favorites

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.

North China 2 (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations

Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations

ImportantThe legacy URL path /api/v2/apps/protocols/compatible-mode/v1/responses will soon be deprecated. Migrate to the new path /compatible-mode/v1/responses as soon as possible.

ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

  • China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

itemsarray (Optional)

A list of up to 20 initial message items.

Properties

typestring(Required)

The message type. Only message is supported.

rolestring(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.

contentstring 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.

metadataobject (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.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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)

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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 --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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."
        }
    ]
}'

Response parameters

created_atinteger

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

idstring

The unique ID of the conversation.

metadataobject

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.

objectstring

The object type. The value is fixed as conversation.

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

Retrieve conversation

Retrieves information for a specified conversation.

North China 2 (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

Singapore: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_idstring(Required, Path)

The conversation ID.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

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

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

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

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

Response parameters

created_atinteger

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

idstring

The unique ID of the conversation.

metadataobject

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.

objectstring

The object type. The value is fixed as conversation.

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

Update conversation

Updates the metadata for a conversation.

North China 2 (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_idstring(Required, Path)

The ID of the conversation.

metadataobject(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.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

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

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

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

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
--data '{
    "metadata": {
        "topic": "update"
    }
}'

Response parameters

created_atinteger

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

idstring

The unique ID of the conversation.

metadataobject

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.

objectstring

The object type. The value is fixed as conversation.

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

Delete conversation

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

North China 2 (Beijing): DELETE https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

Singapore: DELETE https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_idstring(Required, Path)

The conversation ID.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

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

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

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

curl --location --request DELETE 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

Response parameters

deletedboolean

Indicates whether the deletion was successful.

idstring

The ID of the deleted conversation.

objectstring

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

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

Create items

Adds message items to a specified conversation.

North China 2 (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

conversation_idstring(Required, Path)

The ID of the conversation.

itemsarray(Required)

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

Properties

typestring(Required)

The message type. Only message is supported.

rolestring(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.

contentstring 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.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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)

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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 --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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"
            }]
        }
    ]
}'

Response parameters

dataarray[object]

A list of the created message items.

Properties

idstring

The unique ID of the message item.

contentstring or array

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

rolestring

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

statusstring

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

typestring

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

first_idstring

The ID of the first message item in the list.

has_moreboolean

Indicates whether more data is available.

last_idstring

The ID of the last message item in the list.

{
    "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"
}

List items

Lists all message items in a conversation.

North China 2 (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

Singapore: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

conversation_idstring(Required, Path)

The ID of the conversation.

afterstring (Optional)

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

orderstring (Optional)

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

limitinteger (Optional)

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

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

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

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

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

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items?limit=10&order=asc' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

Response parameters

dataarray[object]

A list of the message items.

Properties

idstring

The unique ID of the message item.

contentstring or array

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

rolestring

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

statusstring

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

typestring

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

first_idstring

The ID of the first message item in the list.

has_moreboolean

Indicates whether more data is available.

last_idstring

The ID of the last message item in the list.

objectstring

The object type. The value is fixed as list.

{
    "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"
}

Retrieve item

Retrieves the details for a specified message item.

North China 2 (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

Singapore: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

conversation_idstring(Required, Path)

The ID of the conversation.

item_idstring(Required, Path)

The ID of the message item.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

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

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

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

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items/msg_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

Response parameters

contentarray[object]

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

Properties

typestring

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

textstring

The text content.

idstring

The unique ID of the message item.

rolestring

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

statusstring

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

typestring

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

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

Delete item

Deletes a specified message item.

North China 2 (Beijing): DELETE https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

Singapore: DELETE https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

conversation_idstring(Required, Path)

The ID of the conversation.

item_idstring(Required, Path)

The ID of the message item.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

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

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

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

curl --location --request DELETE 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items/msg_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

Response parameters

deletedboolean

Indicates whether the item was successfully deleted.

idstring

The ID of the deleted message item.

objectstring

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

{
    "deleted": true,
    "id": "msg_xxx",
    "object": "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.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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.8-max", input="How old is Alice?"
)
print(f"First response: {response1.output_text}")

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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.8-max",
  input: "How old is Alice?"
});
console.log("First response:", response1.output_text);

const response2 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.8-max",
  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.
  • Conversation data is retained for a maximum of 7 days and limited to the latest 100 entries. Any data exceeding the time or quantity limit will be automatically cleared.
Previous：OpenAI compatible - EmbeddingNext：LangChain