ai-chat

AI Chat — 统一 LLM 网关

AceDataCloud 提供以下已记录的聊天接口：

端点	用途
POST /aichat2/conversations	推荐用于有状态、多模态和 Agent 式对话
POST /aichat/conversations	旧版对话端点
POST /openai/chat/completions (公共别名 /v1/chat/completions)	兼容 OpenAI 的无状态聊天补全
POST /openai/responses (公共别名 /v1/responses)	兼容 OpenAI 的 Responses API
POST /kimi/chat/completions (公共别名 /v1/chat/completions)	Kimi Chat Completions，支持模型专属的推理控制
POST /v1/messages (别名 /claude/messages)	原生 Claude Messages，包含思考和工具调用
POST /v1/messages/count_tokens (别名 /claude/messages/count_tokens)	统计原生 Claude 输入 Token，不生成输出
POST /v1beta/models/{model}:generateContent	原生 Gemini 内容生成，包含音频输入
POST /v1beta/models/{model}:streamGenerateContent?alt=sse	原生 Gemini SSE 流式传输

首次设置

1. 使用 clawhub install @acedatacloud/ai-chat 安装官方 Skill。确认 ClawHub 发布者是 @acedatacloud。
2. 登录 AceDataCloud → Applications，打开 General application，检查 AI Chat 访问权限、余额和当前价格。复制其 API 密钥，或选择 Manage Keys → Create 创建独立密钥。复制密钥值时不要带上 Bearer ；platform-... 管理令牌不是服务 API 密钥。
3. 如果启用了 Allowed APIs 限制，请为第一个示例添加 /aichat2/conversations；其他聊天路由需要单独授权。下方的高级工作流可能会调用其他路由。
4. 在 OpenClaw Gateway 主机上的 ~/.openclaw/.env 中添加 ACEDATACLOUD_API_TOKEN=your_api_key_here，然后重启 Gateway 并开始新会话。若要直接在终端测试，请在该终端运行 export ACEDATACLOUD_API_TOKEN="your_api_key_here"。切勿将密钥放入提示词或提交 .env 文件。
5. 运行下方的 Quick Start。如果此工作流返回任务 ID，请持续查询同一任务，直到任务完成；不要仅为检查进度而再次提交相同的计费请求。

带图示的密钥设置、首次运行和故障排除指南 · Token 详情

快速开始

推荐：有状态对话

curl -X POST https://api.acedata.cloud/aichat2/conversations \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1","question":"Summarize the latest release notes.","stateful":true}'

兼容 OpenAI 的 SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ACEDATACLOUD_API_TOKEN"],
    base_url="https://api.acedata.cloud/openai"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)
print(response.choices[0].message.content)

Dify：兼容 OpenAI API 的提供方

将 Base URL 设为 https://api.acedata.cloud/v1，将 API Key 设为你的 AceDataCloud 服务令牌，将 model 设为 gpt-5.5（或其他受支持的聊天模型），并将 model type 设为 LLM。选择 conversation type Chat 和 API type Chat Completions。Dify 会自行追加 /chat/completions；请勿使用 /openai/v1，也不要在 Base URL 中包含完整端点。在 Workflow / Chatflow LLM 节点中选择模型之前，请先测试连接。

当前已记录的模型系列

OpenAPI 规范中包含范围广泛且快速更新的模型目录。目前具有代表性的 模型包括：

系列	当前示例
OpenAI / 推理	gpt-6-astra, gpt-6.1-sol, gpt-6-sol, gpt-6-luna, gpt-5.6-luna, gpt-5.6-terra, gpt-5.6-sol-fast, gpt-5.6-sol, gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5.4-pro, gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, o1, o3, o4-mini
OpenAI 免费层级聊天补全	gpt-5.5:free, gpt-5:free, gpt-4.1:free, gpt-4o:free, gpt-4o-mini:free, gpt-oss:free
Claude	claude-opus-5-5 和 claude-sonnet-5-5（仅限 Messages）、claude-fable-5-1、claude-fable-5、claude-opus-5、claude-sonnet-5、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-sonnet-4-20250514、claude-haiku-4-5-20251001、claude-3-7-sonnet-20250219
Gemini	gemini-3.8-flash、gemini-3.6-flash、gemini-3.5-flash、gemini-3.1-pro、gemini-3.1-pro-preview、gemini-3.1-flash-lite-preview、gemini-3-pro-preview、gemini-2.5-flash-lite、gemini-2.0-flash-lite
Grok	grok-4.7、grok-4.5、grok-4、grok-4-0709、grok-3、grok-3-fast
DeepSeek	deepseek-v4.1-flash、deepseek-v4-pro、deepseek-v4-flash、deepseek-r1、deepseek-r1-0528、deepseek-v3、deepseek-v3-250324、deepseek-v3.2-exp
Kimi	kimi-k3.1-pro、kimi-k3、kimi-k2.6、kimi-k2.5、kimi-k2-thinking-turbo、kimi-k2-thinking
GLM	glm-5.2、glm-5.1、glm-5、glm-5-turbo、glm-4.7、glm-4.6、glm-4.5、glm-4.5v、glm-3-turbo

当用户询问推荐模型时，请读取当前公开的 GET https://platform.acedata.cloud/api/v1/models/ 响应，并优先选择适用且 recommended=true 的条目。这是编辑层面的偏好，并不代表授予访问权限，也不意味着新增 API 功能；recommended=false 不代表模型已停用。调用模型前，请检查该模型支持的路由和当前定价；如果用户明确选择了某个模型，不要擅自替换。

目录发现结果取决于发起请求访客的 IP，而非显示语言或 ?country= 覆盖项。中国大陆视图会隐藏标记为 Claude、OpenAI、Gemini 和 Grok 的聊天目录条目。请单独检查媒体可见性：OpenAI 图像生成／编辑功能及其配套指南在中国大陆也会隐藏。请读取服务的 image_unavailable_regions 和 API／文档的 unavailable_regions；不要因仅适用于聊天或图像的限制而隐藏无关媒体或整个混合服务。原始目录响应可能仍保留带标记的条目，因此条目存在并不代表可见。推荐模型时，请遵循当前公开的可见性规则；不要使用缓存的全局列表来宣传在该地区隐藏的聊天或图像功能。目录中缺少某个条目，并不能证明模型已停用或 API 访问权限已撤销：这种展示过滤不会改变 API 路由或计费。请说明目录发现方面的限制，并核实实际账户访问权限和定价；不要擅自替换用户选定的模型。

要选择 gpt-5.6-sol-fast，请在 Chat Completions、Responses、Messages 或上述任一对话端点上发送该确切的公开模型 ID。该模型列于公开模型／定价目录中，并具备视觉能力，但没有公开的模型介绍。请求前请检查账户资格和当前定价；目录可见并不保证能够访问。其定价规则会在记录的 prompt_tokens 超过 272,000 时采用更高层级（恰好为 272,000 时不会）。若发生访问或参数错误，请勿擅自改用 gpt-5.6-sol；具体功能仍取决于模型。

gpt-6.1-sol 支持 low、medium、high、xhigh 和 max 推理力度；不要发送 none 或 minimal。在首周内，访问需要经过验证的 ACE T1+ 持仓或访问授权。请通过平台访问响应检查开放时间。 claude-opus-5-5 和 claude-sonnet-5-5 只能通过专用的 Claude Messages API 使用；不要将其发送到 /openai/chat/completions 或 /aichat2/conversations。

/aichat2/conversations 也接受 model_group 值 chatgpt、claude、gemini、grok、kimi、glm 和 deepseek。

图像生成模型不是聊天模型。 名称以 -image 结尾的模型（例如 gemini-*-image、gpt-4o-image）是图像生成模型；它们 不能用于 OpenAI 兼容聊天、Claude Messages 或会话路由。请改用专用端点生成图像——Gemini 使用 POST /v1beta/models/{model}:generateContent，或 /nano-banana/images。

OpenAI 兼容聊天

POST /openai/chat/completions
{
  "model": "gpt-4.1",
  "messages": [{"role": "user", "content": "Write a haiku about observability."}],
  "stream": true,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "parameters": {"type": "object", "properties": {"location": {"type": "string"}}}
      }
    }
  ]
}

常用参数：

参数	类型	描述
model	字符串	文档中列出的 OpenAI 兼容模型之一
messages	数组	标准 OpenAI 聊天消息列表
temperature / top_p	数字	采样控制参数
max_tokens	整数	输出上限
stream	布尔值	启用 SSE 流式传输
tools / tool_choice	数组 / 字符串对象	函数调用控制参数
service_tier	字符串	处理层级（auto、default、flex、scale、priority）

Kimi 聊天补全

1. 使用相同的 AceDataCloud 服务 Bearer 令牌提交请求前，请先确认 /kimi/chat/completions 当前的 Kimi 访问权限、定价和 Allowed APIs 限制。kimi-k3.1-pro 和 kimi-k3 仍可用；请根据当前公开模型目录中的 recommended 标记选择推荐模型，而不要固定偏好某个模型。不要静默替换明确选定的模型。
2. 将 model 和 messages 发送到 POST /kimi/chat/completions（公开别名 /v1/chat/completions）。K3.1 Pro 支持顶层 reasoning_effort 值 low、high 和 max。K3.1 Pro 和 K3 始终启用推理；不要发送禁用推理的设置。对于 K3，请使用 max 或省略此字段，不要依赖其他值。K2.6 使用 thinking，而非此推理强度控制项。
3. 对于 K3.1 Pro 的图像理解，请在 messages 中使用与文本并列的 image_url 内容块。官方上下文规格最高为 1,048,576 个令牌，但这并不保证是平台对单次请求的限制。使用 Responses 或 Messages 前，请检查所选路由自身的模型列表；共享定价规则并不能证明其支持相应协议。
4. 从 choices[].message.content 读取文本。后续轮次和工具结果交换中，请原样保留完整的助手消息，包括返回时的 reasoning_content 和 tool_calls。仅执行获授权的工具并核实结果；不要伪造响应字段或推理字段。
5. 读取实际的 usage，并在公开模型目录中确认当前的输入、输出和缓存命中定价。不要假定发生了缓存命中，也不要将官方模型价格直接换算为账户费用。

curl -X POST https://api.acedata.cloud/kimi/chat/completions \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"kimi-k3.1-pro",
    "messages":[{"role":"user","content":"Review this code and suggest a repair plan."}],
    "reasoning_effort":"low"
  }'

/aichat2/conversations 也列出了 kimi-k3.1-pro；请使用下方的会话负载，不要假定该路由支持 Kimi 专用的推理强度字段。

原生 Gemini Generate Content

使用原生 Gemini 路由进行音频分析，并使用相同的 AceDataCloud Bearer token。提交前，请确认 Gemini API 访问权限、当前定价、所选的公开模型以及任何 Allowed APIs 限制。这些路由使用 contents 和 parts，而不是 OpenAI messages。

1. 将提示词和音频放入用户内容项的 parts 中。使用带有 mimeType 和 Base64 编码 data 的 inlineData，或带有 mimeType 和 fileUri 的 fileData。此原生接口也接受文本、图像和视频输入、思考配置以及自定义函数声明；这并不意味着 OpenAI 兼容路由或对话路由也支持这些内容。
2. 对于 fileData.fileUri，请使用可通过 HTTPS 直接访问且无需登录的文件。签名 URL 必须在整个请求期间保持有效。将下方的 HTTPS_AUDIO_URL 替换为实际文件 URL，并设置实际音频 MIME 类型；示例假设使用 WAV。
3. 根据文件大小和工作负载设置客户端的总请求超时。非流式音频分析会在模型处理完成后才返回，耗时可能超过 90 秒；90 秒不是服务端处理时限。如果客户端断开连接，服务端仍可能继续处理：不要自动重新提交可能会产生费用的请求。
4. 提交以下原生请求。对于 Gemini 3.x Flash 思考模型，请将 generationConfig.maxOutputTokens 保持在至少 512，以免推理耗尽全部输出预算。

POST /v1beta/models/gemini-3.5-flash:generateContent
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Summarize this audio."},
        {"fileData": {"mimeType": "audio/wav", "fileUri": "HTTPS_AUDIO_URL"}}
      ]
    }
  ],
  "generationConfig": {"maxOutputTokens": 1024}
}

对于流式请求，请将相同的原生请求体发送至 POST /v1beta/models/{model}:streamGenerateContent?alt=sse 并接收 SSE 事件。音频输出、内置工具（codeExecution、googleSearch、urlContext）和显式上下文缓存（cachedContent）均无法保证在所有情况下都可用：请以所选模型的实际响应为准，并呈现错误，不要承诺支持或假定这些字段总会返回 400。

OpenAI Embeddings

使用 POST /openai/embeddings（公开别名 /v1/embeddings）和相同的 AceDataCloud Bearer token 进行语义搜索或 RAG，而不是聊天生成。选择 text-embedding-3-small 或 text-embedding-3-large；model 和 input 为必填项。

POST /openai/embeddings
{
  "model": "text-embedding-3-small",
  "input": "Hello!"
}

text-embedding-ada-002 已停止使用；不要再使用该模型发送新请求。查询现有索引前，请先使用所选的受支持模型重建索引；不要在同一索引中混用不同模型生成的向量，也不要在现有索引中静默切换模型。

原生 Claude 消息

原生 Claude 调用（包括仅支持 Messages 的模型）请使用 POST /v1/messages（公开别名 /claude/messages）。使用相同的 AceDataCloud Bearer token 进行身份验证。必填字段为 model、messages 和 max_tokens；系统指令请使用顶层 system 字段。

curl -X POST https://api.acedata.cloud/v1/messages \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"claude-sonnet-5-5",
    "messages":[{"role":"user","content":"Review this implementation plan."}],
    "max_tokens":8192,
    "thinking":{"type":"adaptive"},
    "output_config":{"effort":"high"}
  }'

• 原样发送 thinking、output_config、effort、采样参数和扩展字段。平台不会强制使用固定的逐模型枚举，也不会改写 thinking 模式；所选模型决定其接受的值和组合，并会将参数错误返回给调用方。透传不代表所有模型或协议都支持相应功能。
• 常见的 thinking.type 值包括 adaptive、enabled 和 disabled；较新的模式（如 between_tools、固定的 budget_tokens）以及能否禁用 thinking，取决于模型。常见的 effort 值包括 low、medium、high、xhigh 和 max，但这些并非封闭枚举。
• thinking.display="summarized" 会返回易读的摘要，而非原始推理内容。omitted 会隐藏 thinking 文本，但保留不透明的 signature。Beta updates 会请求在工具调用之间发送简短进度更新，并隐藏推理内容；请发送 anthropic-beta: thinking-display-updates-2026-08-18 和 thinking.display="updates"。系统会透传该值和 beta 请求头，而不会将其改写为 summarized；实际支持情况和输出取决于所选模型。
• Thinking 与最终文本共用 max_tokens 预算。显示设置不会禁用 thinking，也不会减少其 token 计费量。如果最终答案为空或被截断，请增加预算或降低受支持的 effort。
• 在多轮对话或工具使用对话中，请原样返回完整的助手 thinking 块和签名。切勿编造或编辑签名。跨协议处理 redacted_thinking 取决于模型服务；应明确返回错误，而不是丢弃内容块或静默更改请求。

如需估算输入大小，请使用相同的模型、消息以及适用的 system/tools/thinking 字段，将原生输入发送到 POST /v1/messages/count_tokens（别名 /claude/messages/count_tokens）。读取 input_tokens；此端点不会生成模型输出，也不会消耗配额。其 thinking 配置同样可扩展；请勿使用本地硬编码的模型验证器替代。

有状态／Agentic 对话

POST /aichat2/conversations 扩展了旧版对话 API，支持 多模态用户内容、CRUD 风格的操作以及服务端对话状态。

POST /aichat2/conversations
{
  "action": "chat",
  "model": "claude-sonnet-4-6",
  "message": [
    {"type": "text", "text": "Describe this image."},
    {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
  ],
  "stateful": true,
  "allowed_skills": ["google-search"],
  "allowed_mcp_servers": ["mcp-google-search"]
}

常用参数：

参数	类型	描述
action	字符串	chat、retrieve、retrieve_batch、update、delete
model	字符串	模型名称
question	字符串	简单文本提示词
message	字符串或数组	使用 text、image_url 或 file_url 项表示的多模态内容
stateful	布尔值	在服务端保留对话历史
references	数组	额外的上下文文档
preset	字符串	预设／系统提示词
max_turns	整数	每个请求的 Agent 迭代次数：1–500，默认值为 500；不用于保留历史
allowed_skills / allowed_mcp_servers	数组	限制工具使用范围
unattended_policy	对象	工具使用权限策略
tool_results	数组	返回先前请求的工具调用结果
model_group	字符串	系列选择器（chatgpt、claude、gemini、grok、kimi、glm、deepseek）
offset / limit	整数	用于检索操作的分页参数
callback_url / async	字符串／布尔值	异步执行

请根据预期的工具调用链谨慎设置 max_turns。每次迭代都是一次模型调用，而非历史保留设置；max_turns: 1 表示请求单次回答，不调用工具。省略该参数时最多允许 500 次迭代，但不保证会全部执行。

定时 Agent 任务

使用 https://api.acedata.cloud 上的 POST /aichat2/scheduled-tasks，并提供相同的服务 Bearer 令牌和 aichat API 访问权限。所有操作均使用带有 action 的 POST；此端点不使用平台管理令牌。

1. 创建或启用任务前，确认提示词、模型、账户、允许使用的工具、计划、IANA 时区和支出范围。运行会产生费用，且为无人值守运行：请先以交互方式完成第三方授权，并消除所有需要后续提问的模糊之处。对受支持的写入辅助工具，请使用无人值守确认防护；安排任务不代表默认获得发布或发送权限。
2. 选择 schedule.type：cron 需要五字段 cron 表达式和 tz；interval 需要 interval_seconds 和 tz；once 需要 Unix 秒格式的 at 和 tz。使用 UTC 这类 IANA 时区，而不是 UTC+8。即使设备时区发生变化，保存的时区仍决定 Cron 的墙上时钟时间。
3. 将对话提示词和模型放入 template。可选的 template.max_turns 范围为 1–500，默认值为 500，用于限制每次运行的迭代次数，而非任务频率。每次模型调用都会按实际用量计费；运行也可能因超时、授权或其他执行条件而提前结束。单次运行最长为 15 分钟。必要时设置明确的 Unix 秒格式 ends_at；否则任务会在创建三个月后停止。
4. 创建后，保留返回的任务 id。使用 action="retrieve_batch" 列出任务；使用 action="retrieve_runs" 和该 id 查看执行记录，或使用 action="retrieve_runs_batch" 查看所有任务的执行记录（可选参数：status、offset、limit）。读取每次运行的 status、error_code 和 conversation_id；通过 /aichat2/conversations 获取完整结果。任务的 state="enabled"（在列表中显示为“running”）并不能证明运行成功。
5. 连续的 AI 执行失败不会自动暂停任务：下一次计划运行仍会尝试执行。只有向执行服务移交任务连续失败五次后才会自动暂停，而不是 AI 运行失败五次。余额不足会导致运行失败；需要用户输入或同意的请求会以 awaiting_user_input 失败。检查运行历史，解决余额、授权或提示词问题，并明确暂停反复失败的任务，避免继续尝试。
6. 使用 action="update"、任务 id 和 state="disabled" 暂停；确认后，使用 state="enabled" 恢复。确认要永久移除后，才使用 action="delete" 和 id 删除。

创建载荷（先在本地预览并获得确认，再发送）：

POST /aichat2/scheduled-tasks
{
  "action": "create",
  "name": "Daily AI news summary",
  "schedule": {"type": "cron", "cron": "0 9 * * *", "tz": "UTC"},
  "template": {
    "model": "gpt-4o-mini",
    "question": "Today is {{date}}. Search and summarize the three most important AI news items. Do not publish or send messages.",
    "max_turns": 5
  }
}

POST /aichat2/scheduled-tasks
{"action": "retrieve_runs", "id": "TASK_ID"}

POST /aichat2/scheduled-tasks
{"action": "update", "id": "TASK_ID", "state": "disabled"}

注意事项

• /openai/* 下兼容 OpenAI 的路由保留公开别名 /v1/chat/completions、/v1/responses 和 /v1/embeddings。对于会追加 /chat/completions 的客户端，请使用 Base URL https://api.acedata.cloud/v1（而非 /openai/v1）；上面的 SDK 示例仍使用现有的 /openai 基础路径。
• /aichat2/conversations 上的 POST 是推荐的有状态端点；POST /aichat/conversations 仍供旧版客户端使用。
• /aichat2/conversations 上的 message 可以是多模态内容（text、image_url、file_url）；简单文本提示仍可使用普通的 question。
• /aichat2/conversations 上的 action 不仅限于聊天，还支持 retrieve、retrieve_batch、update 和 delete。
• /openai/chat/completions 文档中列出了 gpt-5.5:free 等免费层模型变体。