AI Chat v2 API 連携説明

AI Chat v2 API（/aichat2/conversations）は新世代の対話インターフェースであり、AI Chat API の全面的なアップグレード版です。v1 の簡潔さとホスト型マルチターン対話を基盤として、以下を拡張しています：

マルチモーダルなユーザー入力：構造化された message フィールドを通じて、テキスト + 画像 + ファイルブロックを直接送信でき、事前に references を使用して間接的に添付する必要はありません。
Agent 化されたツール呼び出し：オンライン検索、Web ページ取得、ファイル読み取りなどのツール一式を内蔵しており、ユーザーが認可した MCP サーバー（Google Drive、Notion、Slack、GitHub など）もマウントできます。モデルは 1 回のリクエスト内で複数回自律的にツールを呼び出し、複雑なタスクを完了できます。
構造化ストリーミングイベント：accept: text/event-stream または application/x-ndjson を通じて、トークンごとの 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 を使用している場合、旧インターフェースも引き続き提供されるため、ご自身のペースで移行できます。

申請プロセス

AI Chat v2 API を使用するには、まず Ace Data Cloud コンソールで API Token を取得し、控えておいてください。

まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインを案内します。完了後、自動的に現在のページへ戻ります。 1 つの API Token だけでプラットフォームのすべてのサービスを呼び出すことができ、サービスごとに個別申請する必要はありません。 初回申請時には無料クレジットが付与され、無料で試用できます。クレジットが不足した場合は、コンソールで共通残高をチャージできます。

📘 完全なドキュメント：AI Chat v2 API →

基本的な使用方法

最も簡単な使用方法は v1 と完全に同じです：model + question を渡し、{answer, id} を取得します。 CURL の例：

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

返却結果：

{
  "answer": "AceDataCloud 是一个聚合主流 AI 模型与多模态服务的统一 API 平台，开发者通过一个密钥即可调用 GPT、Claude、Gemini、Midjourney、Suno、Veo 等多家服务。",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

Python の例：

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-preview、gemini-3.1-pro-preview、gemini-3.1-flash-image、gemini-3.1-pro-preview、gemini-2.5-flash-lite など
xAI：grok-4 など
DeepSeek：deepseek-v4-pro、deepseek-v4.1-flash、deepseek-v4-flash、deepseek-v3.2-exp、deepseek-r1-0528 など
Moonshot：kimi-k3.1-pro、kimi-k3、kimi-k2.6、kimi-k2.5 など
Zhipu：glm-5.3、glm-5.2、glm-5.1、glm-5、glm-5-turbo、glm-4.7、glm-4.5v など

具体的な料金ルールについては、サービスページの Pricing カードを参照してください。

マルチターン対話

v1 と同様に、stateful: true を渡すことで会話保存を有効にします。API は id を返します。後続のリクエストで id を渡せば、自分で messages 履歴を管理することなく対話を継続できます。最初のリクエスト：

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": "记住一个数字：42。"
  }'

返却：

{
  "answer": "好的，我已经记住了 42。需要我用它做什么吗？",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

2 回目のリクエストでは、同じ id を渡します：

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": "我刚才让你记住的数字是多少？"
  }'

{
  "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 の例

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 です：

{"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 による手動の分割解析を使用することを推奨します：

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`	モデルの思考プロセス（選択したモデルが reasoning を公開する場合にのみ出現）。
`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（配列）を渡します。配列の各要素はコンテンツブロックです：

{
  "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 の中核的な強化点は、モデルがツールを自主的に呼び出して複数ステップのタスクを完了できることです。これはデフォルトで有効です。クライアントがリクエスト内で追加の設定を行う必要はありません。一般的なシナリオ：

ユーザーが「最近上海でどんな新しい展覧会があるか調べて」→ モデルが組み込みの web search を呼び出す → 結果を整理して回答する。
ユーザーが「この PDF を読んで要約を書いて」→ モデルが file_read を呼び出す → 要約を書く。
ユーザーが Connections で Google Drive / GitHub / Notion などを認可済み → モデルは対応する MCP ツールを呼び出してそのデータを読み書きできる。

NDJSON / SSE ストリームでは、ツール呼び出しは tool_use と tool_result の2種類のイベントで表現されます。例：

{"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 では、このリクエスト内でモデルがツールを自己呼び出しできる最大ラウンド数を制限できます。範囲は 1～500 で、省略した場合のデフォルトは 500 です。これを小さく設定する（たとえば max_turns: 1）ことで、単一回答を強制し、ツール呼び出しを一切許可しないようにできます。

非同期実行と無人認可

呼び出し元がアラート Webhook、CI/CD、監視システム、またはその他のバックグラウンドタスクである場合、async: true を設定すると、インターフェースは直ちにタスク ID を返し、バックグラウンドで実行を継続します：

{
  "model": "gpt-5.5",
  "async": true,
  "question": "私のサービスでアラートが発生しました。個人用 WeChat を使用して WeChat グループ「AceDataCloudチーム」に通知してください……"
}

返却例：

{
  "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 Server が無人モードで送信、公開、書き込みなどの操作を実行できるようにする場合は、リクエストボディで事前認可リストを明示的に渡してください：

{
  "model": "gpt-5.5",
  "async": true,
  "allowed_skills": ["acedatacloud/personal-wechat"],
  "allowed_mcp_servers": [],
  "question": "私のサービスでアラートが発生しました。個人用 WeChat を使用して WeChat グループ「AceDataCloudチーム」に通知してください……"
}

allowed_skills 内の値は、接続済み Skill の slug です；allowed_mcp_servers 内の値は、接続済み MCP Server の slug です。事前認可リストに含まれていない Skill / MCP Server は、無人モードでは引き続きプレビュー、dry-run、または書き込み操作の実行拒否しかできません。より細かな制御が必要な場合は、同等の unattended_policy オブジェクトを使用することもできます：

{
  "unattended_policy": {
    "allowed_skills": ["acedatacloud/personal-wechat"],
    "allowed_mcp_servers": [],
    "expires_at": 1790000000
  }
}

事前認可とは、この2つのリスト自体のことです：リストが空であれば、いかなる能力も認可されません。追加のスイッチフィールドは不要です。注意：事前認可は「今回のリクエストで、これらの能力が無人モードで人による確認をスキップすることを許可する」ことのみを意味します。具体的な Skill は引き続き --unattended-confirm または対応するセキュリティメカニズムをサポートしている必要があります；そうでない場合、引き続き dry-run となり、書き込み操作が直接実行されることはありません。

一時停止した会話の再開

一部のツールでは、モデルが「ユーザーに質問を返す」ことがあります。このときモデルは ask_user_question イベントを発行し、会話は awaiting_user_input 状態で凍結されます：

{
  "type": "ask_user_question",
  "tool_id": "toolu_01XYZW",
  "tool_name": "ask_user_question",
  "question": "生成するレポートは中国語と英語のどちらを希望しますか？",
  "options": ["中国語", "英語"],
  "id": "f2f4b3e8-..."
}

フロントエンドでこのイベントをカードとしてレンダリングし、ユーザーに回答を選択させた後、同じ id を使用して次のリクエストを開始し、回答を tool_results を通じて戻します：

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 は同じ endpoint 上で action フィールドを通じて軽量な会話管理を提供し、別途 API を開設する必要はありません。

`action: retrieve` —— 会話を取得する

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` —— 会話の要約を一覧表示する

{
  "action": "retrieve_batch",
  "model_group": "chatgpt",
  "limit": 20,
  "offset": 0
}

{ items: [...], total } を返します。要約には messages は含まれません。サイドバーのリストに適しています。ユーザーがある会話を開いた場合は、action: retrieve を使用してその完全なメッセージを個別に取得します。任意のフィルターパラメータ：user_id、application_id、model_group、model。

`action: update` —— タイトルを変更する、または履歴を書き換える

{
  "action": "update",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "title": "杭州旅行计划"
}

messages も渡せますが、サーバー側で厳格な schema 検証が行われます（折りたたまれた ToolUseContent 形式である必要があります）。条件に合わない場合は 400 が返されます。通常は title の変更にのみ使用することを推奨します。

`action: delete` —— 会話を1件削除する

{
  "action": "delete",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

{ id, success: true } を返します。削除後は復元できないため、確認してから呼び出してください。

v1 からのスムーズな移行

すでに /aichat/conversations を使用している場合、v2 への移行ではほとんどコードを変更する必要はありません。

URL を https://api.acedata.cloud/aichat/conversations から https://api.acedata.cloud/aichat2/conversations に変更します。
以前に v1 のモデル名（gpt-3.5、gpt-4-browsing など）を渡していた場合、v2 に切り替える際は現行モデル（gpt-5.4、claude-opus-4-8、gemini-3.1-pro-preview など）へアップグレードすることを推奨します。
NDJSON ストリームのフィールドは後方互換性を維持しています。各 text_delta イベントには引き続き delta_answer と id が含まれるため、従来どおり行ごとに delta_answer を解析するクライアントは変更不要です。

移行後は、必要に応じて v2 の新機能（マルチモーダル message、SSE、ツール呼び出し、action CRUD）を有効化できます。ペースに合わせて進めてください。

エラー処理

エラーレスポンスは統一して以下の形式です。

{
  "error": {
    "code": "chat_error",
    "message": "model service returned an error"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

よくあるエラー：

400 bad_request：必須フィールドの不足、tool_use_id の不一致、messages schema の不正など。
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 との後方互換性を維持しながら、会話を「単発 / 複数ターンのQ&A」から「Agent 化された観測可能な会話」へとアップグレードします。マルチモーダル入力、ツール呼び出し、一時停止 / 再開、ストリーミング構造化イベント、組み込み CRUD を備えています。新規導入では v2 を直接使用することを推奨します。既存の v1 統合は段階的にスムーズに移行できます。ご不明な点があれば、いつでも当社の技術サポートチームまでお問い合わせください。

はじめに

AIチャット

AI画像

AI動画

AIオーディオ

ウェブ＆データ

CAPTCHA

アイデンティティ

Coding

その他のガイド

AI Chat v2 API 連携説明

申請プロセス

基本的な使用方法

マルチターン対話

ストリーミングレスポンス

NDJSON の例

SSE の例

ストリーミングイベントの種類

マルチモーダル入力

v1 `references` との関係

ツール呼び出しと MCP

非同期実行と無人認可

一時停止した会話の再開

会話管理（CRUD）

`action: retrieve` —— 会話を取得する

`action: retrieve_batch` —— 会話の要約を一覧表示する

`action: update` —— タイトルを変更する、または履歴を書き換える

`action: delete` —— 会話を1件削除する

v1 からのスムーズな移行

エラー処理

結論

​申請プロセス

​基本的な使用方法

​マルチターン対話

​ストリーミングレスポンス

​NDJSON の例

​SSE の例

​ストリーミングイベントの種類

​マルチモーダル入力

​v1 references との関係

​ツール呼び出しと MCP

​非同期実行と無人認可

​一時停止した会話の再開

​会話管理（CRUD）

​action: retrieve —— 会話を取得する

​action: retrieve_batch —— 会話の要約を一覧表示する

​action: update —— タイトルを変更する、または履歴を書き換える

​action: delete —— 会話を1件削除する

​v1 からのスムーズな移行

​エラー処理

​結論

申請プロセス

基本的な使用方法

マルチターン対話

ストリーミングレスポンス

NDJSON の例

SSE の例

ストリーミングイベントの種類

マルチモーダル入力

v1 `references` との関係

ツール呼び出しと MCP

非同期実行と無人認可

一時停止した会話の再開

会話管理（CRUD）

`action: retrieve` —— 会話を取得する

`action: retrieve_batch` —— 会話の要約を一覧表示する

`action: update` —— タイトルを変更する、または履歴を書き換える

`action: delete` —— 会話を1件削除する

v1 からのスムーズな移行

エラー処理

結論