用户中心 - 玄鸟造AI

概览

近7天使用趋势

API Key

你的 API Key

用于调用所有 API 接口，请妥善保管。

加载中...

Base URL

https://a.t72p.com/v1

可用模型

模型 ID	上下文	工具调用	思考模式
`volo-model`	32,768 tokens	✅	✅

开发文档

这里补齐了当前项目里真正已经实现的接口、扩展字段、工具调用流程、流式输出细节和原生接口说明。之前文档的主要缺口是：没有写 conversation_id 扩展、没有写 tool_calls 二次回传流程、没有写 cached / ab_test / reasoning_content、没有写常见错误码、没有写平台原生接口。这一版已经补齐，并补充了原生接口字段、用户侧历史/反馈接口、反馈统计、缓存命中说明和兼容边界。

Base URL

/v1

认证方式

Authorization: Bearer YOUR_API_KEY

主要模型

volo-model

会话记忆扩展

conversation_id / conv_id

接口概览

端点	方法	认证	说明
`/v1/chat/completions`	POST	API Key	OpenAI 兼容聊天补全，支持流式、工具调用、reasoning 内容、服务端会话记忆扩展。
`/v1/models`	GET	建议带 API Key	获取当前可用模型列表。
`/api/chat`	POST	API Key	平台原生接口，返回结构更简单，适合你自己的站内前端直接接。
`/api/user.php?action=conversation_messages`	GET	用户登录 Token	取某个 conversation_id 的历史消息，返回 message_id、feedback、response_time、node_type 等字段。
`/api/user.php?action=feedback_save`	POST	用户登录 Token	对 assistant 回复点赞 / 点踩，支持指定 message_id。
`/api/user.php?action=feedback_stats`	GET	用户登录 Token	读取点赞/点踩汇总，以及 A/B bucket 维度统计。

兼容说明：当前实现是 OpenAI Chat Completions 的常用子集兼容，已经支持 messages、max_tokens、temperature、top_p、stream、tools、tool_choice，同时额外支持 conversation_id 作为服务端会话记忆扩展字段；但没有宣称完整覆盖 Responses / Assistants / Realtime 全量接口。

快速开始

cURL

Python

Node.js

工具调用

流式输出

参数说明

原生接口 / 用户接口 / 错误码

1. 先拿模型列表

bash

curl /v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON 响应示例
{
  "object": "list",
  "data": [
    {
      "id": "volo-model",
      "object": "model",
      "owned_by": "volo"
    }
  ]
}

2. 最小可用请求

json

{
  "model": "volo-model",
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "max_tokens": 512
}

JSON 响应示例
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "volo-1.0",
  "conversation_id": "oai_b6f5...",
  "cached": false,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮你的？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 16,
    "total_tokens": 34
  },
  "ab_test": {
    "id": 1,
    "bucket": "control",
    "version_id": 12
  }
}

3. 这套接口里新增的实用扩展

conversation_id把同一会话的请求串起来，服务端会自动回放历史消息并做记忆裁剪。
reasoning_content当底层模型有“思考内容”时，非流式会放在 message.reasoning_content，流式会先逐段输出 reasoning_content，再输出 content。
cached命中精确缓存或语义缓存时会返回 true，便于前端做命中提示。
ab_test命中线上 A/B 测试时会返回 bucket 和 version_id，便于灰度观测。

聊天补全

推荐优先使用 OpenAI 兼容接口。

bash

curl /v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "volo-model",
    "messages": [{"role": "user", "content": "给我一句欢迎语"}],
    "max_tokens": 256,
    "temperature": 0.7,
    "top_p": 0.9
  }'

带 conversation_id 持续对话

bash

curl /v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "volo-model",
    "conversation_id": "demo_conv_001",
    "messages": [
      {"role": "user", "content": "我叫小郭，记住我"}
    ]
  }'

bash

curl /v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "volo-model",
    "conversation_id": "demo_conv_001",
    "messages": [
      {"role": "user", "content": "我刚才叫什么？"}
    ]
  }'

Python（openai 库）

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="/v1"
)

resp = client.chat.completions.create(
    model="volo-model",
    messages=[{"role": "user", "content": "你好"}],
    max_tokens=512,
    temperature=0.7,
    extra_body={"conversation_id": "py_demo_001"}
)

print(resp.choices[0].message.content)
print(getattr(resp.choices[0].message, "reasoning_content", None))

Python 流式输出

python

stream = client.chat.completions.create(
    model="volo-model",
    messages=[{"role": "user", "content": "分两点介绍你自己"}],
    stream=True,
    extra_body={"conversation_id": "py_stream_001"}
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print("[think]", delta.reasoning_content, end="")
    if getattr(delta, "content", None):
        print(delta.content, end="")

Node.js（openai 库）

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "/v1",
});

const resp = await client.chat.completions.create({
  model: "volo-model",
  messages: [{ role: "user", content: "你好" }],
  max_tokens: 512,
  extra_body: { conversation_id: "node_demo_001" },
});

console.log(resp.choices[0].message.content);
console.log(resp.choices[0].message.reasoning_content ?? null);

Node.js 流式输出

javascript

const stream = await client.chat.completions.create({
  model: "volo-model",
  messages: [{ role: "user", content: "输出一个 3 行清单" }],
  stream: true,
  extra_body: { conversation_id: "node_stream_001" },
});

for await (const chunk of stream) {
  const delta = chunk.choices?.[0]?.delta ?? {};
  if (delta.reasoning_content) process.stdout.write("[think]" + delta.reasoning_content);
  if (delta.content) process.stdout.write(delta.content);
}

工具调用完整流程

当前接口支持 OpenAI function calling 格式。完整流程是：第一轮把 tools 发给模型 → 读出 tool_calls → 你的业务代码执行工具 → 把 tool 结果作为新消息回传第二轮。

json - 第1轮请求

{
  "model": "volo-model",
  "messages": [
    {"role": "user", "content": "查询北京天气"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

json - 第1轮响应示例
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"北京\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

json - 第2轮把工具结果回传

{
  "model": "volo-model",
  "messages": [
    {"role": "user", "content": "查询北京天气"},
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_123",
          "type": "function",
          "function": {"name": "get_weather", "arguments": "{\"city\":\"北京\"}"}
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_123",
      "content": "{\"city\":\"北京\",\"weather\":\"晴\",\"temp\":18}"
    }
  ]
}

流式输出（SSE）

设置 stream: true 开启 Server-Sent Events。当前实现会优先透传 reasoning，再输出最终 content；如果模型触发工具，也会透传 tool_calls 增量。

bash

curl -N /v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "volo-model",
    "messages": [{"role": "user", "content": "解释一下缓存命中"}],
    "stream": true
  }'

SSE 事件示例

sse
data: {"choices":[{"delta":{"reasoning_content":"先判断用户意图..."}}]}

data: {"choices":[{"delta":{"reasoning_content":"再结合上下文..."}}]}

data: {"choices":[{"delta":{"content":"缓存命中表示系统直接复用已有答案。"}}]}

data: {"choices":[{"delta":{"content":"这能显著降低响应时间。"}}]}

data: [DONE]

前端处理建议：当 delta 里出现 reasoning_content 时，渲染到“思考面板”；出现 content 时，渲染到最终回答区域；出现 tool_calls 时，进入你的工具执行流程。

请求参数

参数	类型	必填	说明
`model`	string	是	模型 ID，如 `volo-model`。
`messages`	array	是	聊天消息数组，元素包含 `role` 和 `content`；工具调用时 assistant/tool 消息也按 OpenAI 结构回传。
`max_tokens`	int	否	最大生成 token 数，默认 2048，且会受套餐上限约束。
`temperature`	float	否	采样温度，默认走系统设置。
`top_p`	float	否	核采样阈值，默认走系统设置。
`stream`	bool	否	是否以 SSE 流式返回。
`tools`	array	否	OpenAI function calling 工具定义。
`tool_choice`	string / object	否	`auto` / `none` / 指定工具。
`conversation_id`	string	否	服务端扩展字段；传同一个值可复用会话记忆。也兼容 `conv_id`。

非流式响应字段

字段	位置	说明
`reasoning_content`	`choices[0].message`	底层模型的思考文本，有则返回。
`tool_calls`	`choices[0].message`	函数调用请求；此时 `finish_reason` 往往为 `tool_calls`。
`usage`	顶层	prompt/completion/total token 统计。
`conversation_id`	顶层	本次请求绑定的会话 ID。
`cached`	顶层	是否命中缓存。
`ab_test`	顶层	若命中灰度实验，会附带实验 ID、bucket 和版本 ID。

平台原生接口：/api/chat

如果你不是为了兼容 OpenAI SDK，而是自己写站内前端，/api/chat 会更直接。它返回 success / message / reasoning / conversation_id / usage / rate_limit / ab_test 这些字段；命中缓存时还会带 cached / cache_type。

bash

curl /api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "message": "你好",
    "conversation_id": "native_conv_001",
    "stream": false
  }'

站内用户接口：历史消息 / 点赞点踩 / 反馈统计

注意：下面两个接口用的是用户登录 Token，不是 API Key。适合你自己的用户中心、工单台、对话列表页接入。

bash - 取历史消息

curl "/api/user.php?action=conversation_messages&conversation_id=demo_conv_001" \
  -H "Authorization: Bearer USER_LOGIN_TOKEN"

返回会带 messages[].id、feedback、response_time、node_type，方便你做会话详情页和售后排查。

bash - 保存评价

curl /api/user.php?action=feedback_save \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer USER_LOGIN_TOKEN" \
  -d '{
    "conversation_id": "demo_conv_001",
    "message_id": 123,
    "feedback": 1
  }'

bash - 反馈统计

curl "/api/user.php?action=feedback_stats" \
  -H "Authorization: Bearer USER_LOGIN_TOKEN"

常见错误码

HTTP	场景	说明
401	Missing / Invalid API key	Authorization 头缺失或 key 无效。
404	资源不存在	常见于 conversation_id、message_id 不存在。
405	Method not allowed	请求方法不对，例如 GET 调了 POST 端点。
429	Rate limit exceeded	超过套餐速率限制。
502	Upstream model error	上游模型节点调用失败或返回异常。
503	Service busy	节点满载或排队超时，建议重试。

🦞 OpenClaw 接入指南

OpenClaw 是开源的个人 AI 助手平台，支持 WhatsApp、Telegram、飞书、钉钉、Discord 等多渠道接入。
以下教程帮你快速将玄鸟造AI 接入 OpenClaw，支持工具调用和思考模式。

安装 OpenClaw

需要 Node.js ≥ 22。

bash
# 官方安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 或 npm 安装
npm install -g openclaw@latest

# 初始化（选 Skip 跳过模型配置，后面手动填）
openclaw onboard --install-daemon

配置主文件 openclaw.json

打开 ~/.openclaw/openclaw.json（Windows: %USERPROFILE%\.openclaw\openclaw.json），在 models 和 agents 部分填入：

JSON — 合并到 openclaw.json 对应位置

{
  "models": {
    "mode": "merge",
    "providers": {
      "zai": {
        "baseUrl": "https://a.t72p.com/v1",
        "apiKey": "YOUR_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "volo-model",
            "name": "GLM-4.7-Flash",
            "reasoning": true,
            "input": ["text"],
            "cost": {"input":0,"output":0,"cacheRead":0,"cacheWrite":0},
            "contextWindow": 32768,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "zai/volo-model" },
      "models": { "zai/volo-model": {} }
    },
    "list": [
      { "id": "main", "model": "zai/volo-model" }
    ]
  }
}

⚠️ provider 名称必须是 zai（OpenClaw 内置 Z.AI 适配），模型引用格式为 zai/volo-model

配置认证文件 auth-profiles.json

打开 ~/.openclaw/agents/main/agent/auth-profiles.json，替换为：

JSON — 覆盖 auth-profiles.json

{
  "version": 1,
  "profiles": {
    "zai:default": {
      "type": "api_key",
      "provider": "zai",
      "key": "YOUR_API_KEY"
    }
  },
  "lastGood": { "zai": "zai:default" },
  "usageStats": {}
}

⚠️ 字段必须是 type + key（不是 mode/apiKey），key 填明文 API Key

配置模型文件 models.json

打开 ~/.openclaw/agents/main/agent/models.json，替换为：

JSON — 覆盖 models.json

{
  "providers": {
    "zai": {
      "baseUrl": "https://a.t72p.com/v1",
      "apiKey": "YOUR_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "volo-model",
          "name": "GLM-4.7-Flash",
          "reasoning": true,
          "input": ["text"],
          "cost": {"input":0,"output":0,"cacheRead":0,"cacheWrite":0},
          "contextWindow": 32768,
          "maxTokens": 8192
        }
      ]
    }
  }
}

启动并验证

bash
# 检查配置是否正确
openclaw models status

# 启动
openclaw start

# 打开网页控制台
openclaw dashboard

openclaw models status 应显示 Default: zai/volo-model，确认 auth 中 key 不为空。

⚠️ 常见问题

Q: 报 401 Invalid API key

检查三个文件（openclaw.json、auth-profiles.json、models.json）里的 API Key 是否一致且正确。auth-profiles.json 里字段名必须是 type + key。

Q: 报 "Unknown model: anthropic/volo-model"

模型引用必须带 provider 前缀：zai/volo-model，不是 volo-model。检查 agents.defaults.model.primary 字段。

Q: 工具调用（exec）返回问号或失败

确保 API 版本 ≥ v15，支持 tools 参数透传。可用 openclaw models status 确认模型连通。

Q: Rate limit 限速报错

OpenClaw 系统 prompt 较长，建议套餐限速调到 ≥ 30次/分钟。

Q: 显存不足 CUDA OOM

降低 vLLM 的 --max-model-len 和 --max-num-seqs，或加 --enforce-eager 禁用 CUDA Graph。

配置文件位置速查

文件	路径	作用
openclaw.json	`~/.openclaw/openclaw.json`	主配置（模型、agent、网关）
auth-profiles.json	`~/.openclaw/agents/main/agent/auth-profiles.json`	API Key 认证
models.json	`~/.openclaw/agents/main/agent/models.json`	模型配置快照

VOLO

注册 VOLO

近7天使用趋势

你的 API Key

Base URL

可用模型

接口概览

1. 先拿模型列表

2. 最小可用请求

3. 这套接口里新增的实用扩展

聊天补全

带 conversation_id 持续对话

Python（openai 库）

Python 流式输出

Node.js（openai 库）

Node.js 流式输出

工具调用完整流程

流式输出（SSE）

SSE 事件示例

请求参数

非流式响应字段

平台原生接口：/api/chat

站内用户接口：历史消息 / 点赞点踩 / 反馈统计

常见错误码

安装 OpenClaw

配置主文件 openclaw.json

配置认证文件 auth-profiles.json

配置模型文件 models.json

启动并验证

⚠️ 常见问题

配置文件位置速查

更多资源