> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # AI Chat v2 API 連携説明 > AI Dialogue API guide - Ace Data Cloud AI Chat v2 API（`/aichat2/conversations`）は次世代の対話インターフェースであり、[AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations) の全面的なアップグレード版です。v1 のシンプルで、ホスト型のマルチターン対話を基盤として、以下の機能を拡張しています： * **マルチモーダルユーザー入力**：構造化された `message` フィールドを通じて、テキスト + 画像 + ファイルブロックを直接渡すことができ、事前に `references` を使用して間接的に添付する必要がありません。 * **Agent 化されたツール呼び出し**：ネットワーク検索、Web ページ取得、ファイル読み取りなどのツールセットを内蔵しており、ユーザーが認可した MCP サーバー（Google Drive、Notion、Slack、GitHub など）を接続できます。モデルは1回のリクエスト内で複数回自主的にツールを呼び出し、複雑なタスクを完了できます。 * **構造化されたストリーミングイベント**：`accept: text/event-stream` または `application/x-ndjson` を通じて、逐次 token の `text_delta`、`tool_use`、`tool_result`、`thinking`、`citation`、`card`、`artifact` などのイベントを取得でき、フロントエンドで対応するタイプごとに個別レンダリングできます。 * **中断 / 復元可能**：モデルがユーザーから追加情報が必要な場合、`ask_user_question` イベントを送信して一時停止します。次回の呼び出し時に `tool_results` で回答を埋め戻すことで継続できます。 * **新しい CRUD アクションの追加**：同じ endpoint 上で `action` フィールドを通じて `retrieve` / `retrieve_batch` / `update` / `delete` を実行でき、追加の会話管理 API は不要です。 * **継続的に更新されるモデル一覧**：デフォルトで GPT-5.4、Claude Opus 4.8、Claude Sonnet 4.6、Gemini 3.1 Pro、GLM 5.1、DeepSeek V4、Kimi K3 などの最新モデルに接続されています。 同時に、リクエストボディのレベルでは **v1 と完全に後方互換** です：`model` + `question`（+ オプションの `stateful` / `id` / `references` / `preset`）のみを送信すれば、v1 と同等の `{answer, id}` JSON レスポンスを取得できます。そのため `/aichat/conversations` から移行する場合、クライアントを書き直す必要はなく、パスを `/aichat2/conversations` に変更するだけで利用できます。 > 現在 `/aichat/conversations` を使用している場合、旧 API は引き続き提供されますので、ご自身のペースで移行できます。 ## 申請フロー AI Chat v2 API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして API Token を取得し、控えておいてください。 ![](https://cdn.acedata.cloud/5hmkdg.jpg) まだログインまたは登録していない場合、自動的にログインページへ移動し、登録とログインを促されます。完了後、自動的に現在のページへ戻ります。 **1つの API Token でプラットフォーム上のすべてのサービスを呼び出すことができ、サービスごとに個別申請する必要はありません。** 初回申請時には無料クォータが付与され、無料で体験できます。クォータが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。 > 📘 完全なドキュメント：[AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## 基本的な使用方法 最も簡単な使用方法は v1 と完全に同じです：`model` + `question` を渡し、`{answer, id}` を取得します。 CURL 例： ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "question": "一文で AceDataCloud を紹介してください。" }' ``` 返却結果： ```json theme={null} { "answer": "AceDataCloud は主要な AI モデルとマルチモーダルサービスを統合した統一 API プラットフォームであり、開発者は1つのキーだけで GPT、Claude、Gemini、Midjourney、Suno、Veo など複数のサービスを呼び出すことができます。", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Python 例： ```python theme={null} import requests url = "https://api.acedata.cloud/aichat2/conversations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "question": "一文で AceDataCloud を紹介してください。", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` 利用可能な `model` の値は、右側の Try パネルのドロップダウンで直接確認できます。一般的なカテゴリには以下が含まれます： * OpenAI：`gpt-5.4-mini`、`gpt-5.4-nano`、`gpt-5.2-pro`、`gpt-5.1-all`、`gpt-5-all`、`gpt-4.1`、`gpt-4o`、`gpt-4o-image`、`o3`、`o4-mini` など * Anthropic：`claude-opus-4-8`、`claude-opus-4-7`、`claude-opus-4-6`、`claude-opus-4-5-20251101`、`claude-sonnet-4-6`、`claude-sonnet-4-5-20250929`、`claude-haiku-4-5-20251001` など * Google：`gemini-3.1-pro`、`gemini-3.1-pro-preview`、`gemini-3.1-flash-image-preview`、`gemini-3-pro-preview`、`gemini-2.5-flash-lite` など * xAI：`grok-4` など * DeepSeek：`deepseek-v4-flash`、`deepseek-v3.2-exp`、`deepseek-r1-0528` など * Moonshot：`kimi-k3`、`kimi-k2.6`、`kimi-k2.5` など * Zhipu：`glm-5.1`、`glm-5`、`glm-5-turbo`、`glm-4.7`、`glm-4.5v` など 具体的な料金ルールについては、サービスページの Pricing カードを参照してください。 ## マルチターン対話 v1 と同様に、`stateful: true` を渡すことで会話保存を有効にできます。API は `id` を返します。以降のリクエストで `id` を渡すだけで会話を継続でき、自分で messages の履歴を管理する必要はありません。 最初のリクエスト： ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "question": "数字を1つ覚えてください：42。" }' ``` 返却： ```json theme={null} { "answer": "はい、42を覚えました。それを使って何をしますか？", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` 2回目のリクエストでは、同じ `id` を付けます： ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "question": "私がさっき覚えておいてほしいと言った数字は何ですか？" }' ``` ```json theme={null} { "answer": "あなたが私に覚えておいてほしいと言った数字は 42 です。", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` > `stateful` はデフォルトで `true` であり、省略することと明示的に `true` を渡すことは同じです。サーバーがこの対話を保存しないことを望む場合は、明示的に `stateful: false` を設定できます。 ## ストリーミングレスポンス v2 は2種類のストリーミングフォーマットをサポートしており、`accept` ヘッダーによって選択します： | シナリオ | `accept` | データ形態 | | --------------------------- | ------------------------- | ------------------------------------------- | | Web フロントエンド / EventSource | `text/event-stream` | `data: {json}\n\n`、最後の行は `data: [DONE]\n\n` | | サーバー / CLI / Node ストリーミング解析 | `application/x-ndjson` | 各行に1つの JSON オブジェクト | | ストリーミングが不要 | `application/json`（デフォルト） | 一度に `{answer, id}` を返します | ### NDJSON の例 ```python theme={null} import json import requests url = "https://api.acedata.cloud/aichat2/conversations" headers = { "accept": "application/x-ndjson", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "stateful": True, "question": "杭州を三文で紹介してください。", } with requests.post(url, json=payload, headers=headers, stream=True) as resp: answer = "" for line in resp.iter_lines(): if not line: continue event = json.loads(line) if event.get("type") == "text_delta": # v1 との互換性：増分セグメントは delta_answer フィールドを通じて提供されます answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": print() print("usage =", event.get("usage")) ``` NDJSON の各行は構造化されたイベントであり、最も一般的なのは `text_delta` です： ```json theme={null} {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} {"type":"text_delta","content":"州","delta_answer":"州","id":"f2f4b3e8-..."} {"type":"text_delta","content":"は","delta_answer":"は","id":"f2f4b3e8-..."} ... {"type":"done","conversation_id":"f2f4b3e8-...","usage":{"prompt_tokens":21,"completion_tokens":58,"total_tokens":79},"terminal_reason":"natural_stop"} ``` ### SSE の例 ブラウザ側で `EventSource` はカスタムリクエストボディをサポートしていないため、`fetch` + 手動で `\n\n` でスライス解析を使用することをお勧めします： ```javascript theme={null} const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { method: "POST", headers: { accept: "text/event-stream", authorization: "Bearer {token}", "content-type": "application/json", }, body: JSON.stringify({ model: "gpt-5.4", stateful: true, question: "杭州を三文で紹介してください。", }), }); const reader = resp.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; while (true) { const { value, done } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const blocks = buffer.split("\n\n"); buffer = blocks.pop() ?? ""; for (const block of blocks) { const dataLine = block.split("\n").find((l) => l.startsWith("data: ")); if (!dataLine) continue; const payload = dataLine.slice(6); if (payload === "[DONE]") return; const event = JSON.parse(payload); if (event.type === "text_delta") process.stdout.write(event.content); } } ``` ### ストリーミングイベントタイプ | `type` | 意味 | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | `text_delta` | アシスタントの回答の増分テキストセグメント。`content` は新しい内容；v1 との互換性のため、同じイベントは `delta_answer`（`content` と等しい）と `id` を持ちます。 | | `thinking` | モデルの思考プロセス（選択したモデルが推論を公開している場合のみ発生します）。 | | `tool_use` | モデルがツールを呼び出すことを決定し、イベントは `tool_id`、`tool_name`、`input` を持ちます。 | | `tool_result` | ツールの実行結果、前の `tool_use` と `tool_id` でペアリングされ、`is_error` は失敗したかどうかを示します。 | | `card` | ツールが生成した構造化カード（画像、リンクプレビューなど）、直接レンダリングに適しています。 | | `citation` | 対応するテキストセグメントの出典 URL を補足するために使用されます。 | | `ask_user_question` | モデルがユーザーに情報を補充する必要があるときに発生し、対話は `awaiting_user_input` 状態に入ります。詳細は下記の [一時停止した対話の再開](#一時停止した対話の再開) を参照してください。 | | `artifact` | モデルが生成した独立した成果物（コードブロック、文書など）、保存またはダウンロードできます。 | | `system_message` | システムの通知メッセージ（ユーザーとアシスタントの内容ではない）、UI の通知にのみ使用されます。 | | `compact` | 内部コンテキストが圧縮されたイベント、特別な処理は不要です。 | | `error` | このラウンドでエラーが発生し、`message` はエラー内容を説明します。 | | `done` | ストリーミングレスポンスが終了し、`usage`（`prompt_tokens` / `completion_tokens` / `total_tokens` を含む）と `terminal_reason` を持ちます。 | 最終的な答えだけを気にするクライアントは、すべての `text_delta` の `content` を連結することで、`application/json` モードの `answer` と同等になります。 ## マルチモーダル入力 ユーザーの入力に画像やファイルが含まれる場合、`question` の代わりに `message`（配列）を渡します。各配列要素はコンテンツブロックです： ```json theme={null} { "model": "gpt-5.4", "stateful": true, "message": [ { "type": "text", "text": "この画像には猫が何匹いますか？" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } } ] } ``` サポートされているブロックタイプ： * `text` — 通常のテキスト、必須フィールド `text`。 * `image_url` — 画像、必須フィールド `image_url.url`。 * `file_url` — ファイル（PDF、CSV、TXT など）、必須フィールド `file_url.url`。 ### v1 `references` との関係 古いクライアントとの互換性のため、v2 は依然として `references: ["https://...", ...]` フィールドを認識します： * URLの拡張子が `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif` の場合、自動的に `image_url` ブロックに変換されます； * その他の拡張子は `file_url` ブロックに変換されます； * もし `question` も提供されている場合、それを `text` ブロックとして前置きします。 したがって、v1から移行したいがリクエストボディを変更したくない場合は、パスを `/aichat2/conversations` に変更するだけで済みます。元の `references` の使い方はそのまま機能します。 より細かい制御が必要な場合（例えば、複数の画像をテキストの間に配置したり、順序が重要な場合）は、直接 `message` 配列を使用してください。 ## ツール呼び出しとMCP v2のコア強化点は、モデルが自律的にツールを呼び出して複数のタスクを完了できることです。**これはデフォルトで有効になっており**、クライアントがリクエスト内で追加の設定を行う必要はありません。一般的なシナリオ： * ユーザーが「最近の上海の新しい展示を探して」と尋ねる→ モデルが内蔵のウェブ検索を呼び出す→ 結果を整理して回答します。 * ユーザーが「このPDFを読んで要約を書いて」と尋ねる→ モデルがfile\_readを呼び出す→ 要約を書く。 * ユーザーが[Connections](https://platform.acedata.cloud/connections)でGoogle Drive / GitHub / Notionなどを認可している→ モデルは対応するMCPツールを呼び出してデータを読み書きできます。 NDJSON / SSEストリーム内では、ツール呼び出しは `tool_use` と `tool_result` の2種類のイベントで表示されます。例えば： ```json theme={null} {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} {"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."} {"type":"text_delta","content":"現在","delta_answer":"現在","id":"f2f4b3e8-..."} {"type":"text_delta","content":"上海","delta_answer":"上海","id":"f2f4b3e8-..."} ... ``` フロントエンドでツール呼び出しの詳細を表示したくない場合は、`tool_use` / `tool_result` / `card` / `citation` これらのイベントを無視してください。モデルの最終出力は依然として `text_delta` で流れます。 `max_turns` は、今回のリクエストでモデルが自己呼び出しできるツールの最大回数を制限できます。デフォルトの上限はプラットフォームによって決定されます。これを小さく設定（例えば `max_turns: 1`）すると、単一の回答を強制し、ツール呼び出しを許可しません。 ## 非同期実行と無人運用の承認 あなたの呼び出しがアラートWebhook、CI/CD、監視システム、または他のバックグラウンドタスクからのものである場合、`async: true` を設定すると、インターフェースはタスクIDを即座に返し、バックグラウンドで実行を続けます： ```json theme={null} { "model": "gpt-5.5", "async": true, "question": "私のサービスがアラートを出しました。個人のWeChatで「AceDataCloudチーム」のWeChatグループに通知します……" } ``` 返される例： ```json theme={null} { "task_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "conversation_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "status": "queued" } ``` その後、`action: retrieve` + `id` を使用して会話結果を照会できます。また、`callback_url` を提供すると、タスクが完了した後、プラットフォームは `{ status, answer, usage, error }` をあなたのコールバックアドレスにPOSTします。`callback_url` は `http` / `https` を使用する必要があり、`localhost` やプライベートIPのリテラルアドレスを直接記入することはできません。 バックグラウンドタスクは通常、誰も確認をクリックできません。特定のSkillやMCPサーバーが無人運用モードで送信、公開、書き込みなどのアクションを実行することを希望する場合は、リクエストボディに事前承認リストを明示的に伝えてください： ```json theme={null} { "model": "gpt-5.5", "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "question": "私のサービスがアラートを出しました。個人のWeChatで「AceDataCloudチーム」のWeChatグループに通知します……" } ``` `allowed_skills` の値は接続されたSkillのスラッグです；`allowed_mcp_servers` の値は接続されたMCPサーバーのスラッグです。事前承認にリストされていないSkill / MCPサーバーは、無人運用モードではプレビュー、ドライラン、または書き込み操作を拒否することしかできません。 より細かい制御が必要な場合は、同等の `unattended_policy` オブジェクトを使用することもできます： ```json theme={null} { "unattended_policy": { "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "expires_at": 1790000000 } } ``` 事前承認はこの2つのリスト自体を指します：リストが空であれば、いかなる能力も承認されず、追加のスイッチフィールドは必要ありません。 注意：事前承認は「今回のリクエストでこれらの能力が無人運用モードで人工確認をスキップすることを許可する」ことを示します。具体的なSkillは依然として `--unattended-confirm` または対応する安全メカニズムをサポートする必要があります；そうでなければ、ドライランを続け、書き込み操作は直接実行されません。 ## 一時停止した会話の復元 特定のツールはモデルに「ユーザーに再質問させる」ことができます。この時、モデルは `ask_user_question` イベントを発生させ、会話は `awaiting_user_input` 状態で凍結されます： ```json theme={null} { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", "question": "生成するレポートは中国語ですか、それとも英語ですか？", "options": ["中国語", "英語"], "id": "f2f4b3e8-..." } ``` フロントエンドでこのイベントをカードとしてレンダリングし、ユーザーに回答を選択させ、その後同じ `id` を使用して次のリクエストを発起し、回答を `tool_results` で埋め戻します： ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: text/event-stream' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "tool_results": [ { "tool_use_id": "toolu_01XYZW", "output": "中国語" } ] }' ``` リクエストボディ内の `tool_use_id` **は** 一時停止時の `tool_id` と完全に一致する必要があります；一致しない場合は400が返されます。リクエストに `tool_results` が同時に存在する場合、`question` / `message` / `references` はすべて無視されます。 ユーザーがこの質問を放棄することを決定した場合は、新しい `question` / `message` を直接送信すれば、プラットフォームは一時停止したツール呼び出しを「ユーザーがスキップした」として自動的にマークします。 ## セッション管理（CRUD） v2は同じエンドポイントで `action` フィールドを通じて軽量なセッション管理を提供し、別のAPIを開く必要はありません。 ### `action: retrieve` —— セッションを取得する ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "retrieve", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" }' ``` 完全な会話文書を返します（`messages` の履歴、`model`、`title`、`tools_used` などを含む）。 ### `action: retrieve_batch` —— 会話の要約をリスト表示 ```json theme={null} { "action": "retrieve_batch", "model_group": "chatgpt", "limit": 20, "offset": 0 } ``` `{ items: [...], total }` を返します。**要約には `messages` は含まれません**、サイドバーリストに適しています；ユーザーが特定の会話をクリックした場合、`action: retrieve` を使用してその完全なメッセージを個別に取得します。 オプションのフィルターパラメータ：`user_id`、`application_id`、`model_group`、`model`。 ### `action: update` —— タイトルの変更または履歴の書き換え ```json theme={null} { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "title": "杭州旅行计划" } ``` `messages` も送信できますが、サーバーは厳密なスキーマ検証を行います（折りたたまれた `ToolUseContent` 形式でなければなりません）、適合しない場合は 400 を返します。一般的には `title` の変更にのみ使用することをお勧めします。 ### `action: delete` —— 会話を削除 ```json theme={null} { "action": "delete", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` `{ id, success: true }` を返します。削除後は復元できませんので、確認の上で呼び出してください。 ## v1 からのスムーズな移行 もしあなたが [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) を使用している場合、v2 への移行はほとんどコードを変更する必要はありません： 1. URL を `https://api.acedata.cloud/aichat/conversations` から `https://api.acedata.cloud/aichat2/conversations` に変更します。 2. 以前に v1 モデル名（例：`gpt-3.5`、`gpt-4-browsing` など）を送信していた場合、v2 に切り替える際には最新のモデル（例：`gpt-5.4`、`claude-opus-4-8`、`gemini-3.1-pro` など）にアップグレードすることをお勧めします。 3. NDJSON ストリームのフィールドは後方互換性を保持します：各 `text_delta` イベントは引き続き `delta_answer` と `id` を持つため、元々行単位で `delta_answer` を解析していたクライアントは変更する必要はありません。 移行後は必要に応じて v2 の新機能（マルチモーダル `message`、SSE、ツール呼び出し、`action` CRUD）を有効にし、ペースに合わせて進めてください。 ## エラーハンドリング エラー応答は統一されています： ```json theme={null} { "error": { "code": "chat_error", "message": "upstream LLM returned an error" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` 一般的なエラー： * `400 bad_request`：必須フィールドが欠落、`tool_use_id` が一致しない、`messages` スキーマが不正など。 * `401 invalid_token`：`authorization` ヘッダーが不正。 * `404 not_found`：`action: retrieve / update / delete` の際に `id` に対応する会話が存在しない。 * `429 too_many_requests`：レート制限が発動。 * `500 chat_error`：上流の LLM がエラーを返すか、今回の `completion_tokens=0`（未消費として処理され、料金は発生しません）。 ストリーミング応答内では、エラーは `{"type":"error","message":"..."}` イベントとして送信され、その後ストリームは終了します。 ## 結論 AI Chat v2 API は v1 との後方互換性を保ちながら、対話を「単発 / 複数回の質問応答」から「エージェント化された可観測対話」へとアップグレードしました：マルチモーダル入力、ツール呼び出し、一時停止 / 再開、ストリーミング構造化イベント、内蔵 CRUD。新規接続は直接 v2 を使用することをお勧めします；既存の v1 統合は段階的にスムーズに移行できます。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。