OpenAI Conversations介面相容 - Alibaba Cloud Model Studio

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}.ap-southeast-1.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 樣本

使用限制