OpenAI Conversations接口兼容

Create conversation

创建一个新会话，可同时添加初始消息项。 华北2（北京）：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations 新加坡：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations

旧版URL路径 /api/v2/apps/protocols/compatible-mode/v1/conversations 即将停止维护，请尽快迁移至新版路径 /compatible-mode/v1/conversations。

阿里云百炼为华北2（北京）、新加坡地域推出了业务空间专属域名，能够为推理请求提供卓越的性能和更高的稳定性，建议迁移至新域名：

华北2（北京）地域：从 https://dashscope.aliyuncs.com 迁移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
新加坡地域：从 https://dashscope-intl.aliyuncs.com 迁移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

其中 {WorkspaceId} 为您的业务空间 ID，可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。

itemsarray（可选）初始消息项列表，最多20条。

属性

typestring(必选)消息类型，仅支持 message。rolestring(必选)消息的角色。system 与developer 角色的指令优先级高于 user 角色，assistant 角色表示模型在之前交互中生成的消息。取值：user 、assistant 、system 、developer 。contentstring or array(必选)消息内容。支持纯文本字符串或结构化内容列表（如 ResponseInputText 对象数组），列表格式可包含文本等多种内容类型。

metadataobject（可选）会话元数据，用于以结构化格式存储会话的附加信息。最多16对键值对，key最大长度64字符，value最大长度512字符。

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": "李红，一位温婉而坚韧的江南女子，出生在浙江省杭州市，她今年20岁，她的兴趣爱好是琴棋书画。"}
    ]
)
print(conversation)

响应参数

created_atinteger会话创建的 Unix 时间戳（毫秒）。idstring会话唯一标识符。metadataobject会话元数据，以键值对形式存储的附加信息。最多16对，key最大长度64字符，value最大长度512字符。objectstring对象类型，固定为 conversation。

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

Retrieve conversation

获取指定会话的信息。 华北2（北京）：GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id} 新加坡：GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_idstring(必选, Path)会话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)

响应参数

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

Update conversation

更新会话的元数据信息。 华北2（北京）：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id} 新加坡：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_idstring(必选, Path)会话ID。metadataobject(必选)会话元数据，会完全覆盖原有元数据。最多16对键值对，key最大长度64字符，value最大长度512字符。

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)

响应参数

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

Delete conversation

删除指定会话。会话中的消息项不会被删除。 华北2（北京）：DELETE https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id} 新加坡：DELETE https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_idstring(必选, Path)会话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)

响应参数

deletedboolean是否删除成功。idstring被删除的会话ID。objectstring对象类型，固定为 conversation.deleted。

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

Create Items

向指定会话添加消息项。 华北2（北京）：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items 新加坡：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

conversation_idstring(必选, Path)会话ID。itemsarray(必选)消息项列表，每次最多添加20条。

属性

typestring(必选)消息类型，仅支持 message。rolestring(必选)消息的角色。system 、developer角色的指令优先级高于 user 角色，assistant 角色表示模型在之前交互中生成的消息。取值：user、assistant、system、developer。contentstring or array(必选)消息内容。支持纯文本字符串或结构化内容列表（如 ResponseInputText 对象数组），列表格式可包含文本等多种内容类型。

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": "李红的专业是师范教育"}],
        }
    ],
)
print(items.data)

响应参数

dataarray[object]创建的消息项列表。

属性

idstring消息项唯一标识符。contentstring or array消息内容。纯文本字符串或结构化内容列表（如 ResponseInputText 对象数组）。rolestring消息的角色类型，取值：user、assistant、system、developer。statusstring消息的处理状态，取值：in_progress（处理中）、completed（已完成）、incomplete（未完成）。typestring消息项的类型，固定为 message。

first_idstring列表中第一条消息项的ID。has_moreboolean是否还有更多数据。last_idstring列表中最后一条消息项的ID。

{
    "data": [
        {
            "content": [
                {
                    "text": "李红的专业是师范教育",
                    "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

列出会话中的所有消息项。 华北2（北京）：GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items 新加坡：GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

conversation_idstring(必选, Path)会话ID。afterstring（可选）分页游标，返回指定消息ID之后的消息项。orderstring（可选）排序方式，asc（升序）或 desc（降序），默认 desc。limitinteger（可选）返回数量，范围1-100，默认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)

响应参数

dataarray[object]消息项列表。

属性

first_idstring列表中第一条消息项的ID。has_moreboolean是否还有更多数据。last_idstring列表中最后一条消息项的ID。objectstring对象类型，固定为 list。

{
    "data": [
        {
            "content": [
                {
                    "text": "李红，一位温婉而坚韧的江南女子，出生在浙江省，今年20岁",
                    "type": "input_text"
                }
            ],
            "id": "msg_7639f8f6-484b-454a-8125-96a3f40eb9e8",
            "role": "user",
            "status": "completed",
            "type": "message"
        },
        {
            "content": [
                {
                    "text": "李红的闺蜜是小芳",
                    "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

获取指定消息项的详情。 华北2（北京）：GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id} 新加坡：GET

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

conversation_idstring(必选, Path)会话ID。item_idstring(必选, Path)消息项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",
)

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

响应参数

contentarray[object]消息内容列表，包含一个或多个内容对象。

属性

typestring内容类型，如 input_text（用户输入文本）或 output_text（模型输出文本）。textstring文本内容。

idstring消息项唯一标识符。rolestring消息的角色类型，取值：user、assistant、system、developer。statusstring消息的处理状态，取值：in_progress（处理中）、completed（已完成）、incomplete（未完成）。typestring消息项的类型，固定为 message。

{
    "content": [
        {
            "text": "李红的专业是师范教育",
            "type": "input_text"
        }
    ],
    "id": "msg_xxx",
    "role": "user",
    "status": "completed",
    "type": "message"
}

Delete Item

删除指定的消息项。 华北2（北京）：DELETE https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id} 新加坡：DELETE

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

conversation_idstring(必选, Path)会话ID。item_idstring(必选, Path)消息项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.items.delete(
    "msg_xxx",
    conversation_id="conv_xxx"
)
print(result)

响应参数

deletedboolean是否删除成功。idstring被删除的消息项ID。objectstring对象类型，固定为 conversation.item.deleted。

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

Response API 使用 conversation 示例

通过 Responses API 的 conversation 参数，可以实现多轮对话的上下文保持。

请勿同时传入previous_response_id和conversation，否则会报错：[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}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

conversation = client.conversations.create(
    items=[
        {
            "type": "message",
            "role": "system",
            "content": "李红，一位温婉而坚韧的江南女子，出生在浙江省杭州市，她今年20岁，她的兴趣爱好是琴棋书画。",
        }
    ]
)

response1 = client.responses.create(
    conversation=conversation.id, model="qwen3.8-max", input="李红今年多大了"
)
print(f"第一轮响应: {response1.output_text}")

response2 = client.responses.create(
    conversation=conversation.id, model="qwen3.8-max", input="她的兴趣爱好是什么？"
)
print(f"第二轮响应: {response2.output_text}")

使用限制

创建会话或添加消息项时，items 最多包含20条。
metadata 最多16对键值对，key最大长度64字符，value最大长度512字符。
会话信息保留最近7天内的最新100条，超出时间或数量限制的内容将自动清理。

​Create conversation

​响应参数

​Retrieve conversation

​响应参数

​Update conversation

​响应参数

​Delete conversation

​响应参数

​Create Items

​响应参数

​List Items

​响应参数

​Retrieve Item

​响应参数

​Delete Item

​响应参数

​Response API 使用 conversation 示例

​使用限制

Create conversation

响应参数

Retrieve conversation

响应参数

Update conversation

响应参数

Delete conversation

响应参数

Create Items

响应参数

List Items

响应参数

Retrieve Item

响应参数

Delete Item

响应参数

Response API 使用 conversation 示例

使用限制