Conversations API會話管理 - 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，可在百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。

items array（可選）

初始訊息項列表，最多20條。

屬性

type string (必選)

訊息類型，僅支援 message。

role string (必選)

訊息的角色。system 與developer 角色的指令優先順序高於 user 角色，assistant 角色表示模型在之前互動中產生的訊息。取值：user 、assistant 、system 、developer 。

content string 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",
)

conversation = client.conversations.create(
    metadata={"topic": "demo"},
    items=[
        {"type": "message", "role": "system", "content": "李紅，一位溫婉而堅韌的江南女子，出生在浙江省杭州市，她今年20歲，她的興趣愛好是琴棋書畫。"}
    ]
)
print(conversation)

Node.js

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: "李紅，一位溫婉而堅韌的江南女子，出生在浙江省杭州市，她今年20歲，她的興趣愛好是琴棋書畫。"
        }
    ]
});
console.log(conversation);

cURL

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": "李紅，一位溫婉而堅韌的江南女子，出生在浙江省杭州市，她今年20歲，她的興趣愛好是琴棋書畫"
        }
    ]
}'

metadata object（可選）

會話中繼資料，用於以結構化格式儲存會話的附加資訊。最多16對索引值對，key最大長度64字元，value最大長度512字元。

響應參數

created_at integer

會話建立的 Unix 時間戳記（毫秒）。

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

id string

會話唯一識別碼。

metadata object

會話中繼資料，以索引值對形式儲存的附加資訊。最多16對，key最大長度64字元，value最大長度512字元。

object string

物件類型，固定為 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_id string (必選, 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)

Node.js

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

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

響應參數

created_at integer

會話建立的 Unix 時間戳記（毫秒）。

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

id string

會話唯一識別碼。

metadata object

會話中繼資料，以索引值對形式儲存的附加資訊。最多16對，key最大長度64字元，value最大長度512字元。

object string

物件類型，固定為 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_id string (必選, 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",
)

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://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

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

cURL

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

metadata object (必選)

會話中繼資料，會完全覆蓋原有中繼資料。最多16對索引值對，key最大長度64字元，value最大長度512字元。

響應參數

created_at integer

會話建立的 Unix 時間戳記（毫秒）。

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

id string

會話唯一識別碼。

metadata object

會話中繼資料，以索引值對形式儲存的附加資訊。最多16對，key最大長度64字元，value最大長度512字元。

object string

物件類型，固定為 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_id string (必選, 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)

Node.js

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

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

響應參數

deleted boolean

是否刪除成功。

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

id string

被刪除的會話ID。

object string

物件類型，固定為 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_id string (必選, 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",
)

items = client.conversations.items.create(
    "conv_xxx",
    items=[
        {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "李紅的專業是師範教育"}],
        }
    ],
)
print(items.data)

Node.js

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: "李紅的專業是師範教育" }]
            }
        ]
    }
);
console.log(items.data);

cURL

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": "李紅的專業是師範教育"
            }]
        }
    ]
}'

items array (必選)

訊息項列表，每次最多添加20條。

屬性

type string (必選)

訊息類型，僅支援 message。

role string (必選)

訊息的角色。system 、developer角色的指令優先順序高於 user 角色，assistant 角色表示模型在之前互動中產生的訊息。取值：user、assistant、system、developer。

content string or array (必選)

訊息內容。支援純文字字串或結構化內容列表（如 ResponseInputText 對象數組），列表格式可包含文本等多種內容類型。

響應參數

data array[object]

建立的訊息項列表。

屬性

id string

訊息項唯一識別碼。

content string or array

訊息內容。純文字字串或結構化內容列表（如 ResponseInputText 對象數組）。

role string

訊息的角色類型，取值：user、assistant、system、developer。

status string

訊息的處理狀態，取值：in_progress（處理中）、completed（已完成）、incomplete（未完成）。

type string

訊息項的類型，固定為 message。

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

first_id string

列表中第一條訊息項的ID。

has_more boolean

是否還有更多資料。

last_id string

列表中最後一條訊息項的ID。

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_id string (必選, 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",
)

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://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

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

cURL

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'

after string（可選）

分頁遊標，返回指定訊息ID之後的訊息項。

order string（可選）

排序方式，asc（升序）或 desc（降序），預設 desc。

limit integer（可選）

返回數量，範圍1-100，預設20。

響應參數

data array[object]

訊息項列表。

屬性

id string

訊息項唯一識別碼。

content string or array

訊息內容。純文字字串或結構化內容列表（如 ResponseInputText 對象數組）。

role string

訊息的角色類型，取值：user、assistant、system、developer。

status string

訊息的處理狀態，取值：in_progress（處理中）、completed（已完成）、incomplete（未完成）。

type string

訊息項的類型，固定為 message。

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

first_id string

列表中第一條訊息項的ID。

has_more boolean

是否還有更多資料。

last_id string

列表中最後一條訊息項的ID。

object string

物件類型，固定為 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_id string (必選, 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)

Node.js

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

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

item_id string (必選, Path)

訊息項ID。

響應參數

content array[object]

訊息內容列表，包含一個或多個內容對象。

屬性

type string

內容類型，如 input_text（使用者輸入文本）或 output_text（模型輸出文本）。

text string

常值內容。

{
    "content": [
        {
            "text": "李紅的專業是師範教育",
            "type": "input_text"
        }
    ],
    "id": "msg_xxx",
    "role": "user",
    "status": "completed",
    "type": "message"
}

id string

訊息項唯一識別碼。

role string

訊息的角色類型，取值：user、assistant、system、developer。

status string

訊息的處理狀態，取值：in_progress（處理中）、completed（已完成）、incomplete（未完成）。

type string

訊息項的類型，固定為 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_id string (必選, 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)

Node.js

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

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'

item_id string (必選, Path)

訊息項ID。

響應參數

deleted boolean

是否刪除成功。

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

id string

被刪除的訊息項ID。

object string

物件類型，固定為 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.7-plus", input="李紅今年多大了"
)
print(f"第一輪響應: {response1.output_text}")

response2 = client.responses.create(
    conversation=conversation.id, model="qwen3.7-plus", input="她的興趣愛好是什嗎？"
)
print(f"第二輪響應: {response2.output_text}")

Node.js

import OpenAI from "openai";

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

const conversation = await client.conversations.create({
  items: [
    {
      type: "message",
      role: "system",
      content: "李紅，一位溫婉而堅韌的江南女子，出生在浙江省杭州市，她今年20歲，她的興趣愛好是琴棋書畫。"
    }
  ]
});

const response1 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.7-plus",
  input: "李紅今年多大了"
});
console.log("第一輪響應:", response1.output_text);

const response2 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.7-plus",
  input: "她的興趣愛好是什嗎？"
});
console.log("第二輪響應:", response2.output_text);

使用限制

建立會話或添加訊息項時，items 最多包含20條。
metadata 最多16對索引值對，key最大長度64字元，value最大長度512字元。