マルチターン会話ガイド

LLMは自分自身の記憶を持ちません — モデルは、ほんの少し前にあなたが言ったことも覚えていません。「マルチターン会話」とは、実際には毎回のリクエストに会話履歴全体を送ることを意味します。このガイドでは、APIYI における 4 つの呼び出し形式がその履歴をどのように保持するかと、注意すべき落とし穴を説明します。

例ではエンドポイント https://api.apiyi.com と、あなたの APIYI token を使用します。参照しているモデル: gpt-5.4-mini, deepseek-v4-pro, gemini-3.5-flash, claude-sonnet-4-6。

コア原則: 履歴は自分で保持する

一言で言うと、モデルはステートレスであり、あなた（クライアント）が履歴を保持して、毎ターンその全体を再送する ということです。

Turn 1: send [user Q1]                              → get [reply 1]
Turn 2: send [user Q1, reply 1, user Q2]            → get [reply 2]
Turn 3: send [user Q1, reply 1, user Q2, reply 2, user Q3] → get [reply 3]

新しいターンごとに、前回の user メッセージと model の返信を history array の末尾に追加してから、全体を送信します。形式ごとの差分は、history array の呼び名と roles の書き方だけです。

APIYI では、常に「履歴を自分で保持する」方式を使ってください。 サーバー側の会話状態（OpenAI Responses の previous_response_id など）には依存しないでください — ゲートウェイ経由では動作が保証されないためで、その詳細は下の OpenAI ネイティブのセクションで説明しています。

OpenAI互換モード（複数モデルで動作）

最も汎用的な方法で、エンドポイント /v1/chat/completions。履歴は messages 配列にあり、各エントリには role（system / user / assistant）が含まれます。model 文字列を切り替えるだけで、同じコードで別のモデルを動かせます（gpt、deepseek、claude、gemini…）。

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.apiyi.com/v1")

messages = [{"role": "system", "content": "You are a friendly assistant."}]

def chat(user_input, model="gpt-5.4-mini"):
    messages.append({"role": "user", "content": user_input})
    resp = client.chat.completions.create(model=model, messages=messages)
    reply = resp.choices[0].message.content
    messages.append({"role": "assistant", "content": reply})  # append reply to history
    return reply

print(chat("My name is Alice and I'm 28. Please remember."))
print(chat("How old am I? And plus 5?"))   # remembers → 28, 33

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://api.apiyi.com/v1' });
const messages = [{ role: 'system', content: 'You are a friendly assistant.' }];

async function chat(userInput, model = 'gpt-5.4-mini') {
  messages.push({ role: 'user', content: userInput });
  const resp = await client.chat.completions.create({ model, messages });
  const reply = resp.choices[0].message.content;
  messages.push({ role: 'assistant', content: reply });   // append reply to history
  return reply;
}

console.log(await chat("My name is Alice and I'm 28. Please remember."));
console.log(await chat('How old am I?'));

{/* Turn 2: include both the question and answer from turn 1 */}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "My name is Alice and I am 28. Please remember."},
      {"role": "assistant", "content": "Got it: your name is Alice and you are 28."},
      {"role": "user", "content": "How old am I?"}
    ]
  }'

1つのコードベースで、複数モデルに対応: model を deepseek-v4-pro、claude-sonnet-4-6、gemini-3.5-flash、または他の任意のモデルに変更しても、マルチターンのロジックは同じままです。モデルと料金の概要を参照してください。

推論モデルの履歴の扱い

deepseek-v4-pro のような推論モデルは、追加の reasoning_content（思考の連鎖）フィールドを返します。

履歴には content だけを残し、reasoning_content は返さないでください。 思考は現在ターンの中間生成物にすぎず、これを返すと tokens を無駄にし、上流のルールにも違反します（DeepSeek の direct API ではこれに対して 400 が返ることもあります）。履歴へ追加する際は、content だけを使用します：

messages.append({"role": "assistant", "content": resp.choices[0].message.content})
# do NOT include resp.choices[0].message.reasoning_content

推論モデルのレスポンスの解析については、推論モデルの出力を参照してください。

OpenAI ネイティブ形式（Responses API）

エンドポイント /v1/responses。マルチターンでは、input 配列として完全な履歴を渡します（各エントリには role / content を含めます）— compatible mode と同じ自己管理型のアプローチです:

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.apiyi.com/v1")

resp = client.responses.create(
    model="gpt-5.4-mini",
    input=[
        {"role": "user", "content": "Remember the codeword: purple elephant."},
        {"role": "assistant", "content": "Got it, the codeword is purple elephant."},
        {"role": "user", "content": "What's the codeword?"},
    ],
)
print(resp.output_text)   # The codeword is: purple elephant.

サーバー側の状態 のような previous_response_id / conversation / store に依存しないでください。APIYI ゲートウェイ経由で確認したところ、previous_response_id を渡してもエラーにはならず（200 を返します）が、次のターンでは前回の内容を記憶しません。また、GET /v1/responses/{id} は利用できません。したがって APIYI では、上記のように 自己管理型の履歴（input 配列）を使って Responses API を利用してください。

Gemini ネイティブ形式

エンドポイント /v1beta/models/{model}:generateContent。履歴は contents 配列に保持されます。役割は user / model（assistant ではありません）に注意してください。また、各エントリの content は parts に入ります。

from google import genai

client = genai.Client(api_key="YOUR_API_KEY",
                      http_options={"base_url": "https://api.apiyi.com"})

contents = [
    {"role": "user", "parts": [{"text": "Remember the codeword: purple elephant."}]},
    {"role": "model", "parts": [{"text": "Got it: purple elephant."}]},
    {"role": "user", "parts": [{"text": "What's the codeword?"}]},
]
resp = client.models.generate_content(model="gemini-3.5-flash", contents=contents)
print(resp.text)   # The codeword is: purple elephant.

さらに簡単: 公式 google-genai SDK の client.chats.create(...) が contents の履歴を保持してくれるので、send_message を呼ぶだけです。手動でつなぎ合わせる必要はありません。

Gemini 3-series のレスポンスは parts に thoughtSignature を付与します。プレーンテキストのマルチターンでは、text だけを返せばコンテキストを維持できます（tokens も少なくて済みます）。function calling のように厳密な reasoning の継続が必要な場合のみ、thoughtSignature をそのまま返す必要があります。これは公式 SDK が自動で処理します。Gemini Native Calls と Function Calling を参照してください。

Anthropic ネイティブフォーマット

エンドポイント /v1/messages。履歴は messages 配列にあり、ロールは user / assistant です。content は通常の文字列にできます。max_tokens は必須です。

import requests

def chat(messages):
    r = requests.post(
        "https://api.apiyi.com/v1/messages",
        headers={
            "content-type": "application/json",
            "anthropic-version": "2023-06-01",
            "x-api-key": "YOUR_API_KEY",
        },
        json={"model": "claude-sonnet-4-6", "max_tokens": 200, "messages": messages},
        timeout=60,
    )
    return "".join(b["text"] for b in r.json()["content"] if b["type"] == "text")

messages = [{"role": "user", "content": "Remember the codeword: purple elephant."}]
reply = chat(messages)
messages.append({"role": "assistant", "content": reply})       # append reply
messages.append({"role": "user", "content": "What's the codeword?"})
print(chat(messages))   # The codeword is: purple elephant.

公式の anthropic SDK も、base_url を https://api.apiyi.com に指定することで利用できます。レスポンスは content の block 配列です。パースの詳細は Claude Streaming & Responses を参照してください。

4つの形式の比較

項目	OpenAI互換	OpenAIネイティブ（Responses）	Geminiネイティブ	Anthropicネイティブ
エンドポイント	`/v1/chat/completions`	`/v1/responses`	`/v1beta/…:generateContent`	`/v1/messages`
履歴フィールド	`messages`	`input`	`contents`	`messages`
ロール	system/user/assistant	user/assistant	user/model	user/assistant
コンテンツ形式	`content` 文字列	`content` 文字列	`parts: [{text}]`	`content` 文字列
履歴の所有者	あなた	あなた	あなた	あなた
サーバー側の状態	なし	⚠️ 利用不可	なし	なし
モデル横断	✅ `model` を切り替え	OpenAIのみ	Geminiのみ	Claudeのみ

選び方: ベンダーをまたいで 1 つのコードベースを使いたい場合は OpenAI互換モード を優先してください; ベンダー固有のネイティブ専用機能（Gemini の thought signatures / code execution、Claude の thinking blocks とキャッシュ、OpenAI の組み込み tools）が必要なら、その ネイティブ形式 を使ってください。

よくある質問

会話が長くなるほど料金は高くなりますか？

はい。各ターンで履歴全体が再送されるため、input tokens はターン数に応じて増え、それに伴ってコストも上がります。節約の主な方法は コンテキストキャッシュ です。同一の履歴プレフィックスは自動的にキャッシュヒット率が適用され、定価よりはるかに低くなります。OpenAI caching、Claude caching、Gemini caching をご覧ください。

何ターンまで保持すべきですか？コンテキストウィンドウを超えたらどうなりますか？

厳密なルールはありませんが、履歴が長いほどコストは高くなり、モデルのコンテキストウィンドウを超える場合があります。一般的な対処法は次のとおりです。(1) スライディングウィンドウ — 直近の N ターンだけを保持する；(2) 要約圧縮 — 以前のターンを system prompt の段落に要約する；(3) システム指示と直近のターンを常に保持する。ユースケースに必要な「記憶量」とのバランスを取ってください。

system / system instruction はどこに入れればよいですか？

OpenAI 互換と Anthropic: 会話の先頭に置きます（互換版では role:"system" を使用し、Anthropic ではトップレベルの system フィールドまたは最初のメッセージを使います）。Gemini: config.system_instruction を使用します。システム指示は 一度だけ 設定すればよく、毎ターン再追加する必要はありません。

推論モデルの thinking（reasoning_content）を戻すべきですか？

いいえ。 thinking はそのターンの中間生成物です。履歴には最終的な content だけを残してください（Gemini では text のみ）。thinking を返すと token を無駄に消費し、一部の upstream では受け付けられません。例外は、関数呼び出しにおける Gemini の thoughtSignature です。公式 SDK が自動的に処理します。

サーバーに会話を覚えさせて、履歴を再送しなくてもよいですか？

APIYI ではこれは 推奨されません。OpenAI Responses の previous_response_id は、ゲートウェイ経由で確実に動作するとは限りません（検証済み: メモリなし）。どこでもクライアント側で履歴を自前管理する方法を使ってください。これはモデル間で最も安定しており、一貫性があります。

基本

基本API

画像API（公式）

動画API（公式）

マルチモーダル理解API

テキストAPI

マルチターン会話ガイド

コア原則: 履歴は自分で保持する

OpenAI互換モード（複数モデルで動作）

推論モデルの履歴の扱い

OpenAI ネイティブ形式（Responses API）

Gemini ネイティブ形式

Anthropic ネイティブフォーマット

4つの形式の比較

よくある質問

関連リンク

​コア原則: 履歴は自分で保持する

​OpenAI互換モード（複数モデルで動作）

​推論モデルの履歴の扱い

​OpenAI ネイティブ形式（Responses API）

​Gemini ネイティブ形式

​Anthropic ネイティブフォーマット

​4つの形式の比較

​よくある質問

​関連リンク

コア原則: 履歴は自分で保持する

OpenAI互換モード（複数モデルで動作）

推論モデルの履歴の扱い

OpenAI ネイティブ形式（Responses API）

Gemini ネイティブ形式

Anthropic ネイティブフォーマット

4つの形式の比較

よくある質問

関連リンク