OpenAI-compatible - Conversations - Alibaba Cloud Model Studio

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

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

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

Python

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)

Response parameters

created_atintegerThe Unix timestamp in milliseconds that indicates when the conversation was created.idstringThe unique ID of the conversation.metadataobjectThe 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.objectstringThe 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.

Python

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)

Response parameters

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

Python

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)

Response parameters

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

Python

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)

Response parameters

deletedbooleanIndicates whether the deletion was successful.idstringThe ID of the deleted conversation.objectstringThe 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

Python

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)

Response parameters

dataarray[object]A list of the created message items.

Properties

idstringThe unique ID of the message item.contentstring or arrayThe message content. This can be a plain text string or a structured content list, such as a ResponseInputText object array.rolestringThe role of the message. Valid values are user, assistant, system, and developer.statusstringThe processing status of the message. Valid values are in_progress, completed, and incomplete.typestringThe type of the message item. The value is fixed as message.

first_idstringThe ID of the first message item in the list.has_morebooleanIndicates whether more data is available.last_idstringThe 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.

Python

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)

Response parameters

dataarray[object]A list of the message items.

Properties

first_idstringThe ID of the first message item in the list.has_morebooleanIndicates whether more data is available.last_idstringThe ID of the last message item in the list.objectstringThe 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.

Python

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)

Response parameters

contentarray[object]A list of message content that contains one or more content objects.

Properties

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

idstringThe unique ID of the message item.rolestringThe role of the message. Valid values are user, assistant, system, and developer.statusstringThe processing status of the message. Valid values are in_progress, completed, and incomplete.typestringThe 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.

Python

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)

Response parameters

deletedbooleanIndicates whether the item was successfully deleted.idstringThe ID of the deleted message item.objectstringThe 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.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.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}")

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.

​Create conversation

​Response parameters

​Retrieve conversation

​Response parameters

​Update conversation

​Response parameters

​Delete conversation

​Response parameters

​Create items

​Response parameters

​List items

​Response parameters

​Retrieve item

​Response parameters

​Delete item

​Response parameters

​Use conversations in the Responses API

​Limitations

Create conversation

Response parameters

Retrieve conversation

Response parameters

Update conversation

Response parameters

Delete conversation

Response parameters

Create items

Response parameters

List items

Response parameters

Retrieve item

Response parameters

Delete item

Response parameters

Use conversations in the Responses API

Limitations