AI Chat v2 API Integration Guide

The AI Chat v2 API (/aichat2/conversations) is a new-generation conversation interface and a comprehensive upgraded version of the AI Chat API. Building on v1's simplicity and hosted multi-turn conversations, it expands with:

• Multimodal user input: Directly send text + image + file blocks through the structured message field, without needing to attach them indirectly through references first.
• Agent-based tool calling: Includes a built-in set of tools such as web search, webpage fetching, and file reading, and can mount user-authorized MCP servers (Google Drive, Notion, Slack, GitHub, etc.). The model can autonomously call tools across multiple rounds within a single request to complete complex tasks.
• Structured streaming events: Through accept: text/event-stream or application/x-ndjson, you can receive token-by-token events such as text_delta, tool_use, tool_result, thinking, citation, card, and artifact, making it convenient to render them separately by type on the frontend.
• Interruptible / resumable: When the model needs the user to provide additional information, it emits an ask_user_question event and pauses. In the next call, you can fill in the answer through tool_results to continue.
• New CRUD actions: Complete retrieve / retrieve_batch / update / delete through the action field on the same endpoint, without requiring an additional conversation management API.
• Continuously updated model list: By default, it supports contemporary models such as GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, and Kimi K3.

At the request body level, it is fully backward compatible with v1: simply pass model + question (+ optional stateful / id / references / preset) to get a {answer, id} JSON response equivalent to v1. Therefore, when migrating from /aichat/conversations, there is no need to rewrite the client; simply change the path to /aichat2/conversations.

If you are currently using /aichat/conversations, the old interface will remain available, and you can migrate at your own pace.

¶ Application Process

To use the AI Chat v2 API, first go to the 灵蛇云 Console to obtain your API Token and keep it for later use.

If you are not yet logged in or registered, you will be automatically redirected to the login page and invited to register and log in. After completion, you will automatically return to the current page.

One API Token can call all services on the platform; there is no need to apply separately for each service. Your first application comes with free credits for a free trial; when credits are insufficient, you can top up your general balance in the console.

📘 Complete documentation: AI Chat v2 API →

¶ Basic Usage

The simplest usage is exactly the same as v1: pass model + question, and receive {answer, id}.

CURL example:

curl -X POST 'https://api.opensnake.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.4",
    "question": "用一句话介绍下 AceDataCloud。"
  }'

Return result:

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

Python example:

import requests

url = "https://api.opensnake.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())

Available values for model can be viewed directly in the dropdown of the Try panel on the right. Common categories include:

• 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, etc.
• 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, etc.
• 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, etc.
• xAI: grok-4, etc.
• DeepSeek: deepseek-v4-pro, deepseek-v4.1-flash, deepseek-v4-flash, deepseek-v3.2-exp, deepseek-r1-0528, etc.
• Moonshot: kimi-k3, kimi-k2.6, kimi-k2.5, etc.
• Zhipu: glm-5.3, glm-5.2, glm-5.1, glm-5, glm-5-turbo, glm-4.7, glm-4.5v, etc.

For specific billing rules, refer to the Pricing card on the service page.

¶ Multi-turn Conversations

As with v1, pass stateful: true to enable conversation storage. The API will return an id; simply include the id in subsequent requests to continue the conversation, without needing to maintain the messages history yourself.

First request:

curl -X POST 'https://api.opensnake.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。"
  }'

Return:

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

Second request, include the same id:

curl -X POST 'https://api.opensnake.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": "What number did I just ask you to remember?"
  }'

{
  "answer": "The number you asked me to remember is 42.",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

stateful defaults to true; omitting it is equivalent to explicitly passing true. If you do not want the server to save this conversation turn, you can explicitly set stateful: false.

¶ Streaming Responses

v2 supports two streaming formats, selected according to the accept header:

Scenario	accept	Data Format
Web frontend / EventSource	text/event-stream	data: {json}\n\n, with the final line data: [DONE]\n\n
Server / CLI / Node streaming parsing	application/x-ndjson	One JSON object per line
Streaming not required	application/json (default)	Returns {answer, id} in a single response

¶ NDJSON Example

import json
import requests

url = "https://api.opensnake.cloud/aichat2/conversations"

headers = {
    "accept": "application/x-ndjson",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "model": "gpt-5.4",
    "stateful": True,
    "question": "Introduce Hangzhou in three sentences.",
}

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":
            # Compatible with v1: incremental fragments are also provided through the delta_answer field
            answer += event["content"]
            print(event["delta_answer"], end="", flush=True)
        elif event.get("type") == "done":
            print()
            print("usage =", event.get("usage"))

Each line of NDJSON is a structured event; the most common one is text_delta:

{"type":"text_delta","content":"Hang","delta_answer":"Hang","id":"f2f4b3e8-..."}
{"type":"text_delta","content":"zhou","delta_answer":"zhou","id":"f2f4b3e8-..."}
{"type":"text_delta","content":" is","delta_answer":" is","id":"f2f4b3e8-..."}
...
{"type":"done","conversation_id":"f2f4b3e8-...","usage":{"prompt_tokens":21,"completion_tokens":58,"total_tokens":79},"terminal_reason":"natural_stop"}

¶ SSE Example

Using EventSource in the browser does not support custom request bodies. It is recommended to use fetch + manually parse by splitting on \n\n:

const resp = await fetch("https://api.opensnake.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: "Introduce Hangzhou in three sentences.",
  }),
});

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

¶ Streaming Event Types

type	Meaning
text_delta	An incremental text fragment of the assistant's answer. content is the newly added content; for v1 compatibility, the same event also carries delta_answer (equal to content) and id.
thinking	The model's reasoning process (appears only when the selected model exposes reasoning).
tool_use	The model decides to call a tool; the event carries tool_id, tool_name, and input.
tool_result	The tool execution result, paired with the preceding tool_use through tool_id; is_error indicates whether it failed.
card	A structured card produced by a tool (such as an image or link preview), suitable for direct rendering.
citation	The source URL used to supplement citations for the corresponding text fragment.
ask_user_question	Sent when the model needs the user to provide additional information; the conversation enters the awaiting_user_input state. See Resuming Paused Conversations below for details.
artifact	An independent artifact generated by the model (such as a code block or document), which can be saved or downloaded.
system_message	System prompt information (not user or assistant content), used only for UI notifications.
compact	An event indicating that the internal context has been compressed; no special handling is required.
error	An error occurred during this turn; message describes the error content.
done	The streaming response has ended, carrying usage (including prompt_tokens / completion_tokens / total_tokens) and terminal_reason.

For clients that only care about the final answer, concatenating the content of all text_delta events is equivalent to the answer in application/json mode.

¶ Multimodal Input

If user input contains images or files, pass message (an array) instead of question. Each array element is a content block:

{
  "model": "gpt-5.4",
  "stateful": true,
  "message": [
    { "type": "text", "text": "How many cats are in this image?" },
    { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } }
  ]
}

Supported block types:

• text — Plain text; the text field is required.
• image_url — Image; image_url.url is required.
• file_url — File (PDF, CSV, TXT, etc.); file_url.url is required.

¶ Relationship with v1 references

For compatibility with older clients, v2 still recognizes the references: ["https://...", ...] field:

• If the URL suffix is jpg / jpeg / png / gif / bmp / webp / svg / heic / heif, automatically convert it into an image_url block;
• Convert other extensions into a file_url block;
• If question is also provided at the same time, then prepend it as a text block.

Therefore, if you only want to migrate from v1 and do not want to modify the request body, just change the path to /aichat2/conversations; the original references usage will continue to work as usual.

If more fine-grained control is needed (for example, placing multiple images between text, or when the order is important), directly use the message array.

¶ Tool Calls and MCP

The core enhancement of v2 is that the model can autonomously call tools to complete multi-step tasks. This is enabled by default, and the client does not need to make any additional configuration in the request. Common scenarios:

• The user asks, “Help me search for what new exhibitions there are recently in Shanghai” → The model calls the built-in web search → Organizes the results into an answer.
• The user asks, “Read this PDF and then write a summary” → The model calls file_read → Writes a summary.
• The user has authorized Google Drive / GitHub / Notion, etc. in Connections → The model can call the corresponding MCP tools to read and write their data.

In the NDJSON / SSE stream, tool calls are presented through two types of events, tool_use and tool_result, for example:

{"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-..."}
...

If you do not want to display tool call details on the frontend, simply ignore event types such as tool_use / tool_result / card / citation; the model’s final output will still stream through text_delta.

max_turns can limit the maximum number of rounds in which the model can call tools by itself in this request; the default upper limit is determined by the platform. Setting it low (for example, max_turns: 1) can force a single response and disallow any tool calls.

¶ Asynchronous Execution and Unattended Authorization

If your calls come from alert Webhooks, CI/CD, monitoring systems, or other background tasks, you can set async: true to make the API immediately return a task ID and continue execution in the background:

{
  "model": "gpt-5.5",
  "async": true,
  "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……"
}

Response example:

{
  "task_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "conversation_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "status": "queued"
}

Afterward, you can use action: retrieve + id to query the conversation result; you can also provide callback_url, and after the task is completed, the platform will POST { status, answer, usage, error } to your callback address. callback_url must use http / https and cannot directly specify localhost or a private IP literal address.

Usually, there is no one available to click confirmation for background tasks. If you want certain Skills or MCP Servers to perform actions such as sending, publishing, or writing in unattended mode, explicitly pass a pre-authorization list in the request body:

{
  "model": "gpt-5.5",
  "async": true,
  "allowed_skills": ["acedatacloud/personal-wechat"],
  "allowed_mcp_servers": [],
  "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……"
}

The values in allowed_skills are the slugs of connected Skills; the values in allowed_mcp_servers are the slugs of connected MCP Servers. Skills / MCP Servers not included in the pre-authorization list can still only preview, dry-run, or refuse to perform write operations in unattended mode.

If more fine-grained control is needed, you can also use the equivalent unattended_policy object:

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

Pre-authorization is these two lists themselves: an empty list means no capabilities are authorized, and no additional switch field is needed.

Note: Pre-authorization only means “this request allows these capabilities to skip manual confirmation in unattended mode.” The specific Skill must still support --unattended-confirm or the corresponding security mechanism; otherwise, it will continue to dry-run and will not directly perform write operations.

¶ Resuming Paused Conversations

Some tools cause the model to “ask the user a follow-up question.” At this time, the model sends an ask_user_question event, and the conversation is frozen in the awaiting_user_input state:

{
  "type": "ask_user_question",
  "tool_id": "toolu_01XYZW",
  "tool_name": "ask_user_question",
  "question": "你希望生成的报告是中文还是英文？",
  "options": ["中文", "英文"],
  "id": "f2f4b3e8-..."
}

Render this event as a card on the frontend for the user to select an answer, then initiate the next request using the same id and fill the answer back through tool_results:

curl -X POST 'https://api.opensnake.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": "中文"
      }
    ]
  }'

The tool_use_id in the request body must be exactly the same as the tool_id when paused; otherwise, it will return 400. When tool_results exists in the request at the same time, question / message / references will all be ignored.

If the user decides to abandon this question, simply pass a new question / message; the platform will automatically mark the paused tool call as “skipped by user.”

¶ Conversation Management (CRUD)

v2 provides lightweight conversation management through the action field on the same endpoint, without the need to open another API.

¶ action: retrieve —— Retrieve a Conversation

curl -X POST 'https://api.opensnake.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"
  }'

Returns the complete conversation document (including messages history, model, title, tools_used, etc.).

¶ action: retrieve_batch —— List conversation summaries

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

Returns { items: [...], total }. Summaries do not include messages, making them suitable for sidebar lists; if the user opens a conversation, then use action: retrieve to fetch its complete messages separately.

Optional filter parameters: user_id, application_id, model_group, model.

¶ action: update —— Change the title or rewrite history

{
  "action": "update",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "title": "Hangzhou Travel Plan"
}

messages can also be passed, but the server performs strict schema validation (it must be in the folded ToolUseContent form), and returns 400 if it does not comply. Generally, it is only recommended for changing the title.

¶ action: delete —— Delete a conversation

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

Returns { id, success: true }. Deleted conversations cannot be recovered, so please confirm before calling.

¶ Smooth migration from v1

If you are already using /aichat/conversations, migrating to v2 requires almost no code changes:

1. Change the URL from https://api.opensnake.cloud/aichat/conversations to https://api.opensnake.cloud/aichat2/conversations.
2. If you previously used v1 model names (such as gpt-3.5, gpt-4-browsing, etc.), it is recommended to upgrade to current models when switching to v2 (such as gpt-5.4, claude-opus-4-8, gemini-3.1-pro-preview, etc.).
3. NDJSON stream fields remain backward compatible: each text_delta event still includes delta_answer and id, so clients that originally parse delta_answer line by line do not need to be changed.

After migration, you can enable the new v2 capabilities as needed (multimodal message, SSE, tool calling, action CRUD) and proceed at your own pace.

¶ Error handling

Error responses follow a unified format:

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

Common errors:

• 400 bad_request: Missing required fields, mismatched tool_use_id, invalid messages schema, etc.
• 401 invalid_token: The authorization header is incorrect.
• 404 not_found: The conversation corresponding to the id does not exist when using action: retrieve / update / delete.
• 429 too_many_requests: The rate limit has been triggered.
• 500 chat_error: An upstream LLM error occurred, or completion_tokens=0 for this turn (treated as not consumed and will not be charged).

In streaming responses, errors are emitted as {"type":"error","message":"..."} events, followed immediately by the end of the stream.

¶ Conclusion

While remaining backward compatible with v1, the AI Chat v2 API upgrades conversations from “single-turn / multi-turn Q&A” to “observable agent-based conversations”: multimodal input, tool calling, pausable / resumable interactions, structured streaming events, and built-in CRUD. New integrations are recommended to use v2 directly; existing v1 integrations can migrate smoothly in stages. If you have any questions, please feel free to contact our technical support team.