使用概述

呱呱聚合提供与 OpenAI 兼容的 API 接口，同时内置智能路由引擎，

🔌

OpenAI 兼容

完全兼容 OpenAI API 格式，一行代码即可迁移

🧠

智能路由

根据行业身份和偏好自动匹配最优模型

🚀

多模型聚合

一次接入，畅享 GLM、Kimi、DeepSeek 等主流模型

📊

用量统计

实时查看调用日志、Token 消耗和模型分布

快速开始

只需三步即可接入呱呱聚合 API：

1

注册账号

访问注册页面创建呱呱聚合账号。

2

创建 API Key

登录后进入用户中心，在「API Key 管理」中创建新的 Key。

💡 提示

API Key 创建后仅显示一次，请妥善保存。如遗失可在用户中心重新生成。

3

发起请求

使用创建的 API Key 发起对话请求：

curl 
curl https://guaguahub.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer *** \
  -d '{
    "model": "smart",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下自己"}
    ]
  }'

鉴权说明

呱呱聚合 API 使用 API Key 进行身份验证。请在请求头中加入 Authorization 字段。

http 
Authorization: Bearer ***
⚠️ 安全提示

请勿将 API Key 硬编码在客户端代码中，也不要提交到公开的代码仓库。

Base URL

呱呱聚合 API 的基础地址如下：

url 
https://guaguahub.com/v1

注意：仅支持 HTTPS 协议，HTTP 请求将自动重定向至 HTTPS。

所有 API 端点都基于该地址。例如对话补全的完整 URL 为：

POST https://guaguahub.com/v1/chat/completions

Anthropic 协议接入

平台对外同时支持两种接口协议，你可以任选其一调用同样的模型，模型名保持不变（如 glm-4-flash、deepseek-v4-pro）：

  • OpenAI 兼容协议：POST /v1/chat/completions，使用 Authorization: Bearer <API Key> 鉴权。
  • Anthropic 原生协议：POST /v1/messages，可用 x-api-key 或 Authorization: Bearer 鉴权。适合 Claude Code、Cursor、Anthropic 官方 SDK 等默认使用 Anthropic 协议的客户端直连。

接口地址

POST https://guaguahub.com/v1/messages

请求示例（非流式）

curl 
curl https://guaguahub.com/v1/messages \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "anthropic-version: 2023-06-01" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "glm-4-flash",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

响应示例

{
  "id": "msg_xxxxxxxxxxxx",
  "type": "message",
  "role": "assistant",
  "model": "glm-4-flash",
  "content": [
    { "type": "text", "text": "你好！有什么可以帮你的吗？" }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 9, "output_tokens": 12 }
}

流式输出

请求体加上 "stream": true 即可获得标准 Anthropic SSE 事件流（message_start → content_block_delta → message_stop），与 Anthropic 官方格式完全一致。

在 Claude Code / Anthropic SDK 中使用

把客户端的 Base URL 指向本平台，API Key 填你在用户中心创建的密钥即可：

bash 
export ANTHROPIC_BASE_URL=https://guaguahub.com
export ANTHROPIC_API_KEY=YOUR_API_KEY

说明：两种协议共用同一套计费、智能路由与额度，调用哪种协议都按实际消耗的 token 计费，无差别。

对话补全

对话补全接口兼容 OpenAI Chat Completions API，支持流式输出。将 model 参数设为 "smart" 即可启用智能路由。

请求地址

POST /v1/chat/completions

请求参数

参数 类型 必填 说明
model string 是 模型名称，使用"smart"启用智能路由，或指定具体模型如"glm-5.1"
messages array 是 对话消息列表，每个消息包含role和content
stream boolean 否 是否使用流式输出，默认false
temperature number 否 采样温度，范围 0~2，默认0.7
max_tokens integer 否 最大生成 Token 数

请求示例

json 
{
  "model": "smart",
  "messages": [
    {"role": "system", "content": "你是一个专业的编程助手"},
    {"role": "user", "content": "用 Python 写一个快速排序"}
  ],
  "stream": true,
  "temperature": 0.7
}

响应示例

json 
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699123456,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "以下是快速排序的 Python 实现..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

流式响应

当stream: true时，响应为 SSE 流格式：

text 
data: {"id":"...","choices":[{"delta":{"content":"你好"}}]}

data: {"id":"...","choices":[{"delta":{"content":"！"}}]}

data: [DONE]

模型列表

通过以下接口获取当前可用的模型列表：

GET /v1/models

支持的路由模式

模型标识 说明
smart 智能路由，根据用户配置自动选择最优模型
glm-5.1 智谱 GLM-5.1，综合能力强，适合复杂推理与代码
glm-5-turbo 智谱 GLM-5-Turbo，速度快、性价比高
kimi-k2.6 Moonshot Kimi-K2.6，长上下文、文档理解出色
MiniMax-M2.7 MiniMax-M2.7，中文创意写作与对话见长
deepseek-v4-pro DeepSeek-V4-Pro，代码与数学能力突出
deepseek-v4-flash DeepSeek-V4-Flash，轻量快速，适合高频简单任务

图像与视频生成

图像与视频生成复用同一个对话补全接口 /v1/chat/completions，无需学习新的 API。只要把 model 换成对应的生成模型，把要画的内容写进 messages 即可。返回结果是标准的 chat.completion 结构，生成的图片/视频以链接形式放在 content 字段里（Markdown 语法），链接 24 小时内有效。

请求地址

POST /v1/chat/completions

图像生成

把 model 设为图像模型，content 写画面描述（prompt），即可返回一张高清图片。约 20 秒出图。

可用图像模型

seedream  seedream-5.0  seedream-5.0-lite  seedream-4.5  seedream-4.0

视频生成

把 model 设为视频模型，content 写画面描述，即可返回一段约 5 秒的高清短视频，自带运镜与音效。出片较慢（约 1-3 分钟），请把客户端超时时间设为 300 秒以上。

可用视频模型

seedance  seedance-2.0  seedance-2.0-fast  seedance-1.5-pro  seedance-1.0-pro  seedance-1.0-pro-fast

请求示例

bash 
curl https://guaguahub.com/v1/chat/completions \
  -H "Authorization: Bearer $PAPERAIX_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "model": "seedream",
    "messages": [
      {"role": "user", "content": "一只戴墨镜的柯基在沙滩上奔跑"}
    ]
  }'

图像返回示例

content 为 Markdown 文本：![生成图片](图片链接) 展示图片，后附原图链接与生成信息。第三方应用可用正则从 content 中提取图片 URL。

json 
{
  "id": "chatcmpl-f649493c85b4...",
  "object": "chat.completion",
  "model": "seedream",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "已为你生成图片 🎨\n\n![生成图片](https://...volces.com/...seedream...jpeg?X-Tos-Expires=86400&...)\n\n[点击查看原图](https://...volces.com/...jpeg?...)\n\n> 模型：seedream ｜ 共 1 张 ｜ 链接 24 小时内有效"
      },
      "finish_reason": "stop"
    }
  ]
}

视频返回示例

视频以 ::guaguavideo{src=... download=...} 指令（directive）形式返回（用于在呱呱聚合对话页内嵌播放器），并同时附带标准 Markdown 下载链接 [点击下载/查看视频](视频链接)。第三方应用请从 content 中提取 .mp4 链接使用。

json 
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "seedance",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "已为你生成视频 🎬\n\n::guaguavideo{src=\"https://...volces.com/...seedance...mp4?X-Tos-Expires=86400&...\" download=\"https://...mp4?...\"}\n\n[点击下载/查看视频](https://...volces.com/...mp4?...)\n\n> 模型：seedance ｜ 规格：720p 5s ｜ 链接 24 小时内有效"
      },
      "finish_reason": "stop"
    }
  ]
}

使用建议

  • 视频生成耗时较长，务必将 HTTP 客户端超时设为 300 秒以上，避免提前断开。
  • 返回的图片/视频链接有效期为 24 小时，请及时下载转存到自己的存储。
  • 图像与视频生成为同步等待，不支持流式返回（stream 参数会被忽略）。
  • 返回的 content 是 Markdown / 指令文本，第三方应用需自行从中提取媒体 URL（图片为 .jpeg，视频为 .mp4）。

智能路由引擎

呱呱聚合的核心特性是智能路由。当model设置为"smart"时，

路由决策因素

  • 行业身份：软件开发、建筑行业、医学行业、教育等
  • 偏好模式：经济模式（优先性价比）或质量优先（优先效果）
  • 任务类型：代码生成、文档理解、创意写作、数据分析等

配置路由偏好

登录后进入用户中心，在「智能路由引擎」区域配置：

json 
// 路由配置示例（通过用户中心界面设置）
{
  "industry": "software",      // 行业：software | architecture | medical | education
  "subIndustry": "web-dev",    // 子行业：web-dev | mobile | ai | backend
  "preference": "quality",     // 偏好：economy | balanced | quality
  "language": "zh"             // 语言偏好：zh | en
}

行业配置

不同行业对应的最佳模型选择策略：

行业 经济模式推荐 质量优先推荐
软件开发 DeepSeek-V4-Pro GLM-5.1 / Kimi-K2.6
建筑行业 GLM-5.1 Kimi-K2.6
医学行业 GLM-5.1 Kimi-K2.6
教育 DeepSeek-V4-Pro GLM-5.1
通用 MiniMax-M2.7 GLM-5.1

指定单个模型

智能路由（<code>smart</code>）会自动帮你挑选最优模型，但如果你心里已经有明确的选择——

只需把请求里的model字段填成具体的模型标识即可，调用方式和 OpenAI 完全一致：

指定模型调用 
curl https://guaguahub.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kimi-k2.6",
    "messages": [{ "role": "user", "content": "你好" }]
  }'

可指定的模型标识见上方模型列表，目前支持 6 个：

  • glm-5.1 · glm-5-turbo
  • kimi-k2.6
  • MiniMax-M2.7
  • deepseek-v4-pro · deepseek-v4-flash
💡 两种模式自由切换

用smart让呱呱聚合帮你智能选模型、省成本；想自己说了算时，直接填具体模型名即可。

工具集成

呱呱聚合支持多种主流 Coding Agent 和 AI 工具接入。只需配置 Base URL 和 API Key，即可在您喜爱的工具中使用呱呱聚合的智能路由能力。

💡 编程端点

呱呱聚合提供 OpenAI 兼容协议端点：https://guaguahub.com/v1

支持的 Coding Agent 工具

🎯

Claude Code

Anthropic 推出的 AI 编程助手，支持自然语言编程

查看接入指南 →
✨

Cursor

AI 原生 IDE，智能代码编辑器

查看接入指南 →
🔧

Cline

VS Code 扩展，提供智能代码补全和调试

查看接入指南 →
🌐

OpenCode

开源编码工具，支持多种编程语言

查看接入指南 →
⚡

Crush

终端 AI 编程工具，支持 CLI 和 TUI 界面

查看接入指南 →
🚀

Goose

AI Agent 工具，支持本地运行和自动化任务

查看接入指南 →

通用配置步骤

1

获取 API Key

登录呱呱聚合用户中心，在「API Key 管理」中创建新的 Key。

2

配置工具

在您的 Coding Agent 工具中，找到模型/Provider 设置，添加自定义 OpenAI 兼容端点。

3

填写配置信息

填入呱呱聚合的 Base URL 和您的 API Key，选择模型即可开始使用。

Claude Code

Claude Code 是 Anthropic 推出的智能编码工具，在终端中运行，通过自然语言命令交互帮助开发者快速完成代码生成、调试、重构等任务。

步骤一：安装 Claude Code

前提条件：Node.js 18 或更新版本

bash 
# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

步骤二：配置呱呱聚合

选择以下任意一种方式配置环境变量：

方式一：自动化脚本（推荐）

bash 
# 下载并运行呱呱聚合环境配置脚本（macOS / Linux）
curl -O "https://guaguahub.com/install/guaguahub-env.sh" && bash ./guaguahub-env.sh

方式二：手动配置

编辑或创建 Claude Code 配置文件~/.claude/settings.json：

json 
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_PAPERAIX_API_KEY",
    "ANTHROPIC_BASE_URL": "https://guaguahub.com/v1",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
⚠️ 注意

配置完成后，请重新打开一个新的终端窗口，以便环境配置生效。

步骤三：开始使用

bash 
# 进入项目目录
cd your-project

# 启动 Claude Code
claude

模型映射（可选）

Claude Code 内部使用 Claude 模型名称，可通过环境变量映射到呱呱聚合模型：

json 
{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.1",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash"
  }
}

Cursor

Cursor 是 AI 优先的代码编辑器，支持自定义模型配置。

配置步骤

1

打开 Models 设置

在 Cursor 中，打开「Settings」→「Models」部分，点击「Add Custom Model」。

2

选择 OpenAI 协议

选择OpenAI Compatible作为 Provider 类型。

3

填写配置

  • API Key：填入您的呱呱聚合 API Key
  • Override OpenAI Base URL：https://guaguahub.com/v1
  • 模型：输入smart或具体模型如glm-5.1
4

保存并使用

保存设置，在编辑器中选择刚创建的 Provider 即可开始使用。

Cline (VS Code)

Cline 是 VS Code 的 AI 编程插件，支持代码生成和文件操作。

配置步骤

1

打开 Cline 设置

在 VS Code 中，点击 Cline 扩展的设置图标。

2

选择 API Provider

选择OpenAI Compatible或OpenAI。

3

填写配置信息

  • Base URL：https://guaguahub.com/v1
  • API Key：您的呱呱聚合 API Key
  • Model：选择「Use Custom」并输入smart或glm-5.1
4

高级设置（可选）

  • 取消勾选Support Images（如不需要多模态）
  • 调整Context Window Size为200000
  • 根据需求调整temperature等参数

OpenCode

OpenCode 是面向开发者的开源 Coding Agent，在终端中提供代码生成、编辑与任务执行能力。

配置步骤

1

安装 OpenCode

npm install -g @opencode/opencode
2

配置 Provider

编辑 OpenCode 配置文件，添加呱呱聚合作为 Provider：

json 
{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "paperaix": {
      "type": "openai",
      "baseUrl": "https://guaguahub.com/v1",
      "apiKey": "YOUR_PAPERAIX_API_KEY",
      "model": "smart"
    }
  }
}
3

启动使用

opencode --provider paperaix

其他工具

以下工具同样支持通过 OpenAI 兼容协议接入呱呱聚合：

工具 说明 配置方式
Crush 终端 AI 编程工具，支持 CLI 和 TUI 界面 配置文件中添加 OpenAI 兼容 Provider
Goose AI Agent 工具，支持本地运行和自动化任务 Extensions → Add custom extension → HTTP 类型
Roo Code VS Code 插件，用于项目代码编写重构 OpenAI Compatible Provider
Kilo Code 高效的 VS Code 插件，专注性能优化 OpenAI Compatible Provider
TRAE 能独立完成各类开发任务的 AI 编辑器 自定义模型配置
CodeBuddy 基于 AI 的全流程智能编程工具 自定义 API 端点
Lingma 阿里云智能编程助手 自定义模型配置
💡 通用配置模板

所有支持 OpenAI 协议的工具，核心配置均为：

  • Base URL：https://guaguahub.com/v1
  • API Key：您的呱呱聚合 API Key
  • Model：smart（智能路由）或具体模型名称

如何切换模型

呱呱聚合支持在工具中灵活切换模型，满足不同的编码需求。

在 Claude Code 中切换

编辑配置文件~/.claude/settings.json，修改模型映射：

json 
{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.1",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k2.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash"
  }
}

在 Cursor 中切换

在 Cursor 的 Models 设置中，直接修改已添加的 Custom Model 的模型名称即可。

在 Cline 中切换

在 Cline 扩展设置中，修改 Model 字段为想要的模型标识，如glm-5.1、kimi-k2.6等。

💡 推荐使用 smart 模式

将模型设置为smart，呱呱聚合会根据您的行业配置和偏好自动选择最优模型，无需手动切换。

MCP 服务

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，用于标准化 AI 模型与外部工具、数据源之间的交互。呱呱聚合提供多个专属 MCP 服务，增强您的 Coding Agent 能力。

🔍

联网搜索

让 AI 拥有实时网络搜索能力，获取最新信息

👁️

视觉理解

图像分析、视频理解、UI 截图转代码

📄

网页读取

抓取任意网页内容，提取结构化数据

📦

开源仓库

GitHub 仓库检索、代码读取、文档搜索

视觉理解 MCP

为 Claude Code 等客户端提供图像分析、视频理解等视觉能力。

功能特性

  • 图像分析：支持多种图像格式的智能分析和内容理解
  • 视频理解：支持本地视频与远端视频的视觉理解
  • 简单集成：一键安装，快速集成到 MCP 兼容客户端

支持的工具

工具名 说明
ui_to_code 将 UI 截图转换为代码、设计规范或自然语言描述
extract_text 从截图中提取和识别文字（OCR）
diagnose_error 解析错误弹窗、堆栈截图，给出定位与修复建议
analyze_diagram 针对架构图、流程图、UML 等技术图纸生成结构化解读
analyze_chart 阅读仪表盘、统计图表，提炼趋势与业务要点
ui_diff_check 对比两张 UI 截图，识别视觉差异和实现偏差
image_analysis 通用图像理解能力
video_analysis 支持 MP4/MOV 等格式的视频场景解析

环境变量配置

环境变量 说明 默认值
PAPERAIX_API_KEY 呱呱聚合 API Key 必需配置

Claude Code 配置

bash 
# 一键安装命令
claude mcp add -s user vision-mcp \
  --env PAPERAIX_API_KEY=YOUR_API_KEY \
  -- npx -y "@paperaix/mcp-vision"

手动配置

json 
{
  "mcpServers": {
    "vision-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@paperaix/mcp-vision"],
      "env": {
        "PAPERAIX_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
💡 使用提示

将图片放到本地目录，通过对话指定图片路径来调用 MCP：

What does demo.png describe?

网页读取 MCP

为 Claude Code 等客户端提供网页内容抓取能力，获取网页详细内容和结构化数据。

功能特性

  • 网页内容抓取：支持抓取任意网页的完整内容
  • 结构化数据：提取网页的标题、正文、元数据等
  • 远程服务：基于 HTTP 协议，无需本地安装

支持的工具

工具名 说明
webReader 抓取指定 URL 的网页内容，返回标题、正文、元数据、链接列表等

示例场景

  • API 文档读取：自动抓取并解析官方文档，提炼要点摘要
  • 开源项目解析：解析项目官网或仓库页面，提取核心信息
  • 技术文章理解：从博客、教程提取步骤、命令与注意事项
  • BUG 参考修复：读取网页公开信源，参考修复问题

Claude Code 配置

bash 
# 一键安装命令
claude mcp add -s user -t http web-reader \
  https://guaguahub.com/mcp/reader \
  --header "Authorization: Bearer ***

手动配置

json 
{
  "mcpServers": {
    "web-reader": {
      "type": "http",
      "url": "https://guaguahub.com/mcp/reader",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

开源仓库 MCP

为 Claude Code 等客户端提供 GitHub 仓库的知识文档与代码访问功能。

功能特性

  • 文档搜索：GitHub 代码仓库检索文档、代码与注释
  • 仓库结构：获取目录结构和文件列表，快速掌握项目布局
  • 代码读取：读取指定文件的完整代码内容，深入分析实现细节

支持的工具

工具名 说明
search_doc 搜索 GitHub 仓库的知识文档、新闻、Issue、PR 等
get_repo_structure 获取仓库目录结构和文件列表
read_file 读取指定文件的完整代码内容

示例场景

  • 快速上手开源库：搜索文档和获取仓库结构，加速学习曲线
  • 排查 Issue：搜索仓库 Issue 和 Commit 历史，查找解决方案
  • 深入源码分析：读取核心文件代码，分析实现逻辑
  • 依赖库调研：评估依赖库的活跃度、代码质量和维护情况

Claude Code 配置

bash 
# 一键安装命令
claude mcp add -s user -t http zread \
  https://guaguahub.com/mcp/zread \
  --header "Authorization: Bearer ***

手动配置

json 
{
  "mcpServers": {
    "zread": {
      "type": "http",
      "url": "https://guaguahub.com/mcp/zread",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

错误码

HTTP 状态码 错误类型 说明
400 Bad Request 请求参数错误，请检查请求体格式
401 Unauthorized API Key 无效或已过期
403 Forbidden 权限不足，当前 Key 无权访问该模型
429 Too Many Requests 请求频率超限，请降低调用频率
500 Internal Server Error 服务器内部错误，请稍后重试
503 Service Unavailable 模型服务暂时不可用，正在自动切换备用模型

错误响应格式

json 
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

速率限制

为保障服务稳定性，API 调用存在以下限制：

限制项 免费版 标准版 专业版
RPM（每分钟请求数） 20 100 500
TPM（每分钟 Token 数） 10,000 100,000 1,000,000
并发请求数 2 10 50
💡 提示

当接近速率限制时，响应头中会包含X-RateLimit-Remaining字段。