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

メッセージリストを手動で管理すると、複数のデバイスや長時間の休憩にわたる会話においてコンテキストの損失を引き起こす可能性があります。Alibaba Cloud Model Studio は、OpenAI 互換 Conversations API を提供しています。この API を Responses API と組み合わせて使用すると、履歴コンテキストを自動的に挿入できます。これにより、メッセージを手動で同期する必要がなくなり、さまざまなシナリオやデバイス間でシームレスな会話の継続性が可能になります。

会話の作成

新しいセッションを作成し、初期メッセージアイテムを追加します。

中国本土: POST https://dashscope.aliyuncs.com/compatible-mode/v1/conversations

国際: POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations

重要

レガシー URL パス /api/v2/apps/protocols/compatible-mode/v1/conversations は、メンテナンスのため間もなく非推奨となります。新しいパス /compatible-mode/v1/conversations へ早急に移行してください。

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://dashscope.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://dashscope.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://dashscope.aliyuncs.com/compatible-mode/v1/conversations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
--data '{
    "metadata": {
        "topic": "デモ"
    },
    "items": [
        {
            "type": "メッセージ",
            "role": "システム",
            "content": "李紅（リーホン）さんは、中国浙江省杭州市出身の20歳の女性です。優しく、そしてたくましい性格です。趣味は琴、囲碁、書道、絵画です。"
        }
    ]
}'

metadata object (オプション)

セッションのメタデータ。このフィールドを使用して、セッションに関する追加の構造化情報を格納します。最大 16 個のキーと値のペアをサポートします。キーは最大 64 文字長、値は最大 512 文字長です。

応答パラメーター

created_at integer

セッションが作成されたときの Unix タイムスタンプ (ミリ秒単位)。

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

id string

セッションの一意の識別子。

metadata object

セッションのメタデータ。これはキーと値のペアとして格納される追加情報です。最大 16 個のペアをサポートします。キーは最大 64 文字長、値は最大 512 文字長です。

object string

オブジェクトタイプ。これは、値が conversation の静的フィールドです。

会話の取得

特定のセッションに関する情報を取得します。

中国本土: GET https://dashscope.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

国際: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_id string (必須, パス)

セッション ID。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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://dashscope.aliyuncs.com/compatible-mode/v1",
});

const conversation = await client.conversations.retrieve(
    "conv_xxx"
);
console.log(conversation);

cURL

curl --location 'https://dashscope.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

object string

オブジェクトタイプ。これは、値が conversation の静的フィールドです。

会話の更新

セッションのメタデータを更新します。

中国本土: POST https://dashscope.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

国際: POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_id string (必須, パス)

セッション ID。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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://dashscope.aliyuncs.com/compatible-mode/v1",
});

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

cURL

curl --location 'https://dashscope.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 個のキーと値のペアをサポートします。キーは最大 64 文字長、値は最大 512 文字長です。

応答パラメーター

created_at integer

セッションが作成されたときの Unix タイムスタンプ (ミリ秒単位)。

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

id string

セッションの一意の識別子。

metadata object

object string

オブジェクトタイプ。これは、値が conversation の静的フィールドです。

会話の削除

特定のセッションを削除します。セッション内のメッセージアイテムはそのまま残ります。

中国本土: DELETE https://dashscope.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

国際: DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

conversation_id string (必須, パス)

セッション ID。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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://dashscope.aliyuncs.com/compatible-mode/v1",
});

const result = await client.conversations.del(
    "conv_xxx"
);
console.log(result);

cURL

curl --location --request DELETE 'https://dashscope.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 の静的フィールドです。

アイテムの作成

特定のセッションにメッセージアイテムを追加します。

中国本土: POST https://dashscope.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

国際: POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

conversation_id string (必須, パス)

セッション ID。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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://dashscope.aliyuncs.com/compatible-mode/v1",
});

const items = await client.conversations.items.create(
    "conv_xxx",
    {
        items: [
            {
                type: "message",
                role: "user",
                content: [{ type: "input_text", text: "Li Hong の専攻は教員養成です" }]
            }
        ]
    }
);
console.log(items.data);

cURL

curl --location 'https://dashscope.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 (必須)

content string or array (必須)

応答パラメーター

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。

アイテムのリスト

セッション内のすべてのメッセージアイテムをリスト表示します。

中国本土: GET https://dashscope.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

国際: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items

conversation_id string (必須, パス)

セッション ID。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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://dashscope.aliyuncs.com/compatible-mode/v1",
});

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

cURL

curl --location 'https://dashscope.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": "李紅 (Li Hong) は浙江省出身の、優しくて芯の強い 20 歳の女性です。",
                    "type": "input_text"
                }
            ],
            "id": "msg_7639f8f6-484b-454a-8125-96a3f40eb9e8",
            "role": "user",
            "status": "completed",
            "type": "message"
        },
        {
            "content": [
                {
                    "text": "李紅 (Li Hong) の親友はシャオファン (Xiaofang) です。",
                    "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 の静的フィールドです。

アイテムの取得

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

中国本土: GET https://dashscope.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

国際: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

conversation_id string (必須, パス)

セッション ID。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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://dashscope.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://dashscope.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items/msg_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

item_id string (必須, パス)

メッセージアイテム ID。

応答パラメーター

content array[object]

メッセージコンテンツオブジェクトのリスト。

プロパティ

type string

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

text string

テキストコンテンツ。

{
    "content": [
        {
            "text": "Li Hong の専攻は教員養成教育です",
            "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 https://dashscope.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

国際: DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}

conversation_id string (必須, パス)

セッション ID。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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://dashscope.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://dashscope.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items/msg_xxx' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'

item_id string (必須, パス)

メッセージアイテム ID。

応答パラメーター

deleted boolean

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

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

id string

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

object string

オブジェクトタイプ。これは、値が 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://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

conversation = client.conversations.create(
    items=[
        {
            "type": "message",
            "role": "system",
            "content": "Li Hong は浙江省杭州市出身の 20 歳の女性です。性格は優しく、芯が強いです。趣味は琴、囲碁、書道、絵画です。",
        }
    ]
)

response1 = client.responses.create(
    conversation=conversation.id, model="qwen3.6-plus", input="Li Hong は何歳ですか？"
)
print(f"最初の応答: {response1.output_text}")

response2 = client.responses.create(
    conversation=conversation.id, model="qwen3.6-plus", input="彼女の趣味は何ですか？"
)
print(f"2 番目の応答: {response2.output_text}")

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope-intl.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.6-plus",
  input: "李紅さんは何歳ですか？"
});
console.log("最初の応答:", response1.output_text);

const response2 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.6-plus",
  input: "彼女の趣味は何ですか？"
});
console.log("2回目の応答:", response2.output_text);

使用制限

セッションを作成したりメッセージアイテムを追加したりする場合、items 配列には最大 20 個のアイテムを含めることができます。
metadata オブジェクトには、最大 16 個のキーと値のペアを含めることができます。キーは最大 64 文字長、値は最大 512 文字長です。