会話 API のセッション管理 - Alibaba Cloud Model Studio - Alibaba Cloud ドキュメントセンター

複数のデバイスにまたがる会話や、長期間中断された会話のメッセージリストを手動で管理すると、コンテキストの損失につながる可能性があります。Alibaba Cloud Model Studio は、OpenAI 互換のカンバセーション API を提供しており、レスポンス API と組み合わせて使用することで、履歴コンテキストを自動的に注入できます。これにより、手動でのメッセージの同期が不要になり、さまざまなシナリオやデバイス間での会話の継続性を確保します。

カンバセーションの作成

新しいカンバセーションを作成します。初期メッセージアイテムをオプションで含めることができます。

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

重要レガシー URL パス /api/v2/apps/protocols/compatible-mode/v1/conversations は間もなく非推奨となります。できるだけ早く新しいパス /compatible-mode/v1/conversations に移行してください。

重要Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールの各リージョン向けにワークスペース固有ドメインをリリースしました。これらの新しい専用ドメインにより、推論リクエストのパフォーマンスと安定性が向上します。以下の新しいドメインへの移行を推奨します：

中国 (北京)：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 です。Alibaba Cloud Model Studio コンソールの ワークスペースの詳細 ページで確認できます。既存のドメインは引き続き問題なく利用できます。

items array (省略可能)

最大 20 個の初期メッセージアイテムのリストです。

プロパティ

type string(必須)

メッセージタイプです。message のみがサポートされています。

role string(必須)

メッセージのロールです。system および developer ロールからの指示は、user ロールからの指示よりも優先度が高くなります。assistant ロールは、以前のやり取りでモデルが生成したメッセージを示します。有効な値は user、assistant、system、developer です。

content string または array(必須)

メッセージのコンテンツです。このパラメーターは、プレーンテキスト文字列または構造化されたコンテンツリスト (ResponseInputText オブジェクト配列など) をサポートします。リスト形式には、テキストなどのさまざまなコンテンツタイプを含めることができます。

metadata object (省略可能)

カンバセーションのメタデータです。このパラメーターを使用して、追加のカンバセーション情報を構造化された形式で保存します。最大 16 個のキーと値のペアを指定できます。キーは最大 64 文字、値は最大 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)

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歳の女性です。趣味は音楽とチェスです。"
        }
    ]
}'

レスポンスパラメーター

created_at integer

カンバセーションが作成された日時を示す UNIX タイムスタンプ (ミリ秒単位) です。

id string

カンバセーションの一意の ID です。

metadata object

カンバセーションのメタデータです。このパラメーターは、追加情報をキーと値のペアとして保存します。最大 16 個のペアを含めることができます。キーは最大 64 文字、値は最大 512 文字です。

object string

オブジェクトタイプです。値は conversation に固定されています。

{
    "created_at": 1771316949128,
    "id": "conv_xxx",
    "metadata": {
        "topic": "demo"
    },
    "object": "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_id文字列(必須、パス)

カンバセーション 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整数

カンバセーションが作成された日時を示す UNIX タイムスタンプ (ミリ秒単位) です。

id文字列

カンバセーションの一意の ID です。

メタデータオブジェクト

カンバセーションのメタデータです。このパラメーターは、追加情報をキーと値のペアとして保存します。最大 16 個のペアを含めることができます。キーは最大 64 文字、値は最大 512 文字まで指定できます。

オブジェクト文字列

オブジェクトタイプです。値は conversation に固定されています。

{
    "created_at": 1771316949128,
    "id": "conv_xxx",
    "metadata": {
        "topic": "demo"
    },
    "object": "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(必須、パス)

カンバセーションの ID です。

metadataobject(必須)

カンバセーションのメタデータです。このパラメーターは、既存のメタデータを完全に上書きします。最大 16 個のキーと値のペアを指定できます。キーの長さは最大 64 文字、値の長さは最大 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)

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

応答パラメーター

created_atinteger

カンバセーションが作成された日時を示す、ミリ秒単位の UNIX タイムスタンプです。

idstring

カンバセーションの一意の ID です。

metadataobject

カンバセーションのメタデータです。このパラメーターには、キーと値のペアとして情報が保存されます。最大 16 個のペアを含めることができます。キーの長さは最大 64 文字、値の長さは最大 512 文字です。

objectstring

オブジェクトタイプです。値は conversation に固定されています。

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

カンバセーションの削除

指定のカンバセーションを削除します。カンバセーション内のメッセージ項目は削除されません。

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_id文字列 (必須、パス)

カンバセーション 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ブール値

削除が成功したかどうかを示します。

id文字列

削除されたカンバセーションの ID です。

object文字列

オブジェクトタイプです。値は conversation.deleted に固定されています。

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

アイテムの作成

指定した会話にメッセージアイテムを追加します。

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(必須、パス)

会話の ID です。

itemsarray(必須)

メッセージアイテムのリストです。一度に最大 20 個のアイテムを追加できます。

プロパティ

typestring(必須)

メッセージタイプです。message のみがサポートされています。

rolestring(必須)

メッセージのロールです。system および developer ロールからの指示は、user ロールからの指示よりも優先度が高くなります。assistant ロールは、以前のやり取りでモデルによって生成されたメッセージを示します。有効な値は user、assistant、system、developer です。

contentstring or array(必須)

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": "花子の専門は教員養成です"
            }]
        }
    ]
}'

レスポンスパラメーター

dataarray[object]

作成されたメッセージアイテムのリストです。

プロパティ

idstring

メッセージアイテムの一意の ID です。

contentstring or array

メッセージのコンテンツです。プレーンテキスト文字列または構造化されたコンテンツリスト (ResponseInputText オブジェクト配列など) のいずれかです。

rolestring

メッセージのロールです。有効な値は user、assistant、system、developer です。

statusstring

メッセージの処理ステータスです。有効な値は in_progress、completed、incomplete です。

typestring

メッセージアイテムのタイプです。値は message に固定されています。

first_idstring

リスト内の最初のメッセージアイテムの ID です。

has_moreブール値

追加のデータがあるかどうかを示します。

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

アイテムの一覧表示

会話内のすべてのメッセージ項目を一覧表示します。

North China 2 (Beijing): 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 文字列 (必須、パス)

会話の ID です。

after 文字列 (省略可能)

ページネーションカーソルです。指定されたメッセージ ID より後に作成されたメッセージ項目のみを返します。

order 文字列 (省略可能)

ソート順です。有効な値は asc (昇順) または desc (降順) です。デフォルトは desc です。

limit 整数 (省略可能)

返すアイテム数です。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)

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'

レスポンスパラメータ

data 配列[object]

メッセージ項目のリストです。

プロパティ

id 文字列

メッセージ項目の一意の ID です。

content 文字列または配列

メッセージのコンテンツです。プレーンテキスト文字列、または input_text オブジェクトの配列などの構造化されたコンテンツリストのいずれかです。

role 文字列

メッセージのロールです。有効な値は user、assistant、system、developer のいずれかです。

status 文字列

メッセージの処理ステータスです。有効な値は in_progress、completed、incomplete のいずれかです。

type 文字列

メッセージ項目のタイプです。値は message で固定です。

first_id 文字列

リスト内の最初のメッセージ項目の ID です。

has_more ブール値

さらにデータが利用可能かどうかを示します。

last_id 文字列

リスト内の最後のメッセージ項目の ID です。

object 文字列

オブジェクトタイプです。値は 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"
}

アイテムの取得

指定されたメッセージアイテムの詳細を取得します。

中国北部 2 (北京): 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(必須、パス)

会話の ID です。

item_idstring(必須、パス)

メッセージアイテムの 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(
    "conv_xxx",
    "msg_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'

レスポンスパラメーター

contentarray[object]

1 つ以上のコンテンツオブジェクトを含むメッセージコンテンツのリストです。

プロパティ

typestring

コンテンツタイプです。ユーザー入力テキストの場合は input_text 、モデル出力テキストの場合は output_text などです。

textstring

テキストコンテンツです。

idstring

メッセージアイテムの一意の ID です。

rolestring

メッセージのロールです。有効な値は user 、 assistant 、 system 、 developer です。

statusstring

メッセージの処理ステータスです。有効な値は in_progress 、 completed 、 incomplete です。

typestring

メッセージアイテムのタイプです。値は message に固定されています。

{
    "content": [
        {
            "text": "Alice's major is teacher education",
            "type": "input_text"
        }
    ],
    "id": "msg_xxx",
    "role": "user",
    "status": "completed",
    "type": "message"
}

アイテムの削除

指定のメッセージアイテムを削除します。

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_id文字列 (必須、パス)

会話のIDです。

item_id文字列 (必須、パス)

メッセージアイテムの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'

応答パラメーター

deletedブール値

アイテムが正常に削除されたかどうかを示します。

id文字列

削除されたメッセージアイテムのIDです。

object文字列

オブジェクトタイプです。値は conversation.item.deleted で固定です。

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

Responses API での会話の使用

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": "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}")

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: "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.8-max",
  input: "How old is Alice?"
});
console.log("First response:", response1.output_text);

const response2 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.8-max",
  input: "What are her hobbies?"
});
console.log("Second response:", response2.output_text);

制限

会話を作成する、またはメッセージ項目を追加する際、items 配列には最大 20 件のエントリを含めることができます。
metadata オブジェクトには最大 16 個のキーと値のペアを含めることができます。キーは最大 64 文字、値は最大 512 文字です。
会話データは最大 7 日間保持され、最新 100 件に制限されます。期間または数量制限を超えたデータは自動的に削除されます。