Skip to main content

OpenAI 互換 - 会話

複数のデバイスにまたがる会話や、長期間中断された会話のメッセージリストを手動で管理すると、コンテキストの損失につながる可能性があります。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)

レスポンスパラメーター

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)

応答パラメーター

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)

応答パラメーター

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)

レスポンスパラメーター

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(必須)メッセージのコンテンツです。このパラメーターは、プレーンテキスト文字列または構造化されたコンテンツリスト (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メッセージアイテムの一意の 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)

レスポンスパラメータ

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)

レスポンスパラメーター

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)

応答パラメーター

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

制限

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