OpenAI compatible - Conversations

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/compatible-mode/v1/conversations

International: POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversationsImportant

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. **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/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/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/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/compatible-mode/v1/conversations/{conversation_id}

International: GET https://dashscope-intl.aliyuncs.com/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/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/compatible-mode/v1",
});

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

## cURL

curl --location 'https://dashscope.aliyuncs.com/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/compatible-mode/v1/conversations/{conversation_id}

International: POST https://dashscope-intl.aliyuncs.com/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/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/compatible-mode/v1",
});

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

## cURL

curl --location 'https://dashscope.aliyuncs.com/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/compatible-mode/v1/conversations/{conversation_id}

International: DELETE https://dashscope-intl.aliyuncs.com/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/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/compatible-mode/v1",
});

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

## cURL

curl --location --request DELETE 'https://dashscope.aliyuncs.com/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/compatible-mode/v1/conversations/{conversation_id}/items

International: POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/itemsconversation_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/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/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/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/compatible-mode/v1/conversations/{conversation_id}/items

International: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/itemsconversation_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/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/compatible-mode/v1",
});

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

## cURL

curl --location 'https://dashscope.aliyuncs.com/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/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

International: GET https://dashscope-intl.aliyuncs.com/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/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/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/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/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

International: DELETE https://dashscope-intl.aliyuncs.com/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/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/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/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

HELPCODEESCAPE-python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope-intl.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.6-plus", input="How old is Alice?"
)
print(f"First response: {response1.output_text}")

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

Node.js

HELPCODEESCAPE-javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope-intl.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.6-plus",
  input: "How old is Alice?"
});
console.log("First response:", response1.output_text);

const response2 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.6-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.