MapleGCM API 开发文档
构建下一代 AI 应用的完整解决方案。我们的 API 旨在提供高性能、易集成的 AI 服务,帮助开发者快速构建智能应用。
基础 URL: https://developer.maplegcm.com/v1
认证鉴权
所有 API 请求都需要在 HTTP Header 中包含 Authorization 字段。
Authorization: Bearer sk-gcm-YOUR_SECRET_KEY
您可以在控制台生成以 sk-gcm- 开头的密钥。请务必保管好您的密钥,不要在客户端代码(如浏览器 JS)中暴露。
可用模型
MapleGCM 提供三种模型供您选择:
GCM-2
标准对话模型,适用于大多数文本生成任务。不支持网络搜索功能,适合回答一般性问题、创作、翻译等场景。
- 强大的文本理解和生成能力
- 支持多轮对话
- 支持 Markdown 格式输出
- 流式输出支持
GCM-2-Search
增强版对话模型,内置智能搜索功能。当检测到需要最新信息或专业知识时,会自动进行网络搜索并整合结果。
- 包含 GCM-2 的所有功能
- 智能判断是否需要搜索
- 自动提取搜索关键词
- 整合搜索结果到回答中
- 适合需要实时信息的场景
GCM-2-Thinking
深度推理模型,采用思维链技术,并具备联网搜索能力。擅长解决需要实时信息辅助的复杂逻辑、数学和代码问题。
- 深度逻辑分析与思维链 (CoT)
- 内置联网搜索功能
- 代码生成与优化
- 输出包含
<thinking>过程
GCM-Optimize
文本优化专用模型。专注于对输入的文本进行润色、语法修正和逻辑优化。
新增参数: 请求体中支持 type 参数,控制润色风格。
type: "spoken"- 口语化、自然,适合对话脚本。type: "professional"- (默认) 专业、严谨,适合商务文档。type: "daily"- 日常、通顺,适合社交媒体或普通交流。
{
"model": "GCM-Optimize",
"type": "spoken",
"messages": [{"role": "user", "content": "这玩意儿咋用啊"}]
}
计费说明
MapleGCM 采用按量计费模式,透明公正。
| 模型 | 输入价格 (每1k tokens) | 输出价格 (每1k tokens) |
|---|---|---|
| GCM-2 (标准版) | ¥0.007 | ¥0.06 |
| GCM-2-Search (联网版) | ¥0.01 | ¥0.08 |
| GCM-2-Thinking (推理版) | ¥0.015 | ¥0.10 |
| GCM-Optimize (润色版) | ¥0.005 | ¥0.05 |
注:1 token 约等于 0.75 个英文单词或 0.5 个中文字符。新用户注册即送 ¥10 体验额度。
对话 (Chat Completions)
核心对话接口,支持 GCM-2, GCM-2-Search 和 GCM-2-Thinking 模型。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型ID:GCM-2, GCM-2-Search 或 GCM-2-Thinking |
| messages | array | 是 | 消息列表,每个消息包含 role (system/user/assistant) 和 content |
| stream | boolean | 否 | 是否开启流式传输 (SSE),默认 true,推荐开启 |
| temperature | number | 否 | 采样温度,范围 0-2,默认 0.7。值越高越随机 |
消息格式
每个消息对象包含以下字段:
role:"system"(系统提示)、"user"(用户消息)或"assistant"(助手回复)content: 消息内容(字符串)
请求示例
curl https://developer.maplegcm.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-gcm-xxxxxx" \
-d '{
"model": "GCM-2",
"messages": [
{"role": "system", "content": "你是一个专业的AI助手。"},
{"role": "user", "content": "请介绍一下你自己"}
],
"stream": true
}'
响应格式
流式响应采用 Server-Sent Events (SSE) 格式,每个数据块格式如下:
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"GCM-2","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"GCM-2","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
data: [DONE]
搜索功能
GCM-2-Search 模型内置智能搜索功能,能够自动判断是否需要搜索并整合结果。
工作原理
- 智能判断:AI 自动分析用户问题,判断是否需要网络搜索
- 关键词提取:如果需要搜索,自动提取最相关的搜索关键词
- 执行搜索:调用搜索引擎获取最新信息
- 结果整合:将搜索结果整合到回答中,提供准确、实时的信息
使用场景
- 需要最新信息的查询(如"今天天气如何"、"最新的科技新闻")
- 需要专业知识的回答(如"某个技术的最新进展")
- 需要实时数据的查询(如"当前股价"、"最新政策")
示例代码
import requests
import json
API_KEY = "sk-gcm-YOUR_KEY"
API_URL = "https://developer.maplegcm.com/v1/chat/completions"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
}
data = {
"model": "GCM-2-Search",
"messages": [
{"role": "user", "content": "2024年最新的AI技术突破有哪些?"}
],
"stream": True
}
response = requests.post(API_URL, headers=headers, json=data, stream=True)
# ... 处理流式响应 ...
注意:搜索功能仅在 GCM-2-Search 模型中可用。使用 GCM-2 模型时不会进行搜索。
深度推理
GCM-2-Thinking 模型采用先进的思维链技术,在回答前会先输出思考过程。
返回格式
模型返回的内容将包含两个部分:思考过程和最终回答。
<thinking>
这里是模型对于问题的深度分析和推理过程...
1. 分析问题核心...
2. 拆解逻辑步骤...
3. 验证推导结果...
</thinking>
这里是最终的回答结果。
建议在前端展示时,解析 <thinking> 标签,并将其渲染为可折叠的“思考过程”区域,以提供更好的用户体验。
# 使用 GCM-2-Thinking
response = client.chat.completions.create(
model="GCM-2-Thinking",
messages=[
{"role": "user", "content": "请证明费马大定理"}
],
stream=True
)
模型列表 (Models)
获取所有可用模型的列表。
响应示例
{
"object": "list",
"data": [
{
"id": "GCM-2",
"object": "model",
"created": 1686935002,
"owned_by": "maplegcm"
},
{
"id": "GCM-2-Search",
"object": "model",
"created": 1699935002,
"owned_by": "maplegcm"
},
{
"id": "GCM-2-Thinking",
"object": "model",
"created": 1704067200,
"owned_by": "maplegcm"
}
]
}
Markdown 格式支持
GCM-2 和 GCM-2-Search 模型支持在输出中使用 Markdown 格式,让您的应用能够展示富文本内容。
支持的 Markdown 语法
| 语法 | 示例 | 输出效果 |
|---|---|---|
| 标题 | # 一级标题## 二级标题 | 不同大小的标题 |
| 粗体 | **粗体文本** | 粗体文本 |
| 斜体 | *斜体文本* | 斜体文本 |
| 代码 | `代码` | 行内代码 |
| 代码块 | ```语言 | 语法高亮的代码块 |
| 列表 | - 项目1 | 无序列表 |
| 有序列表 | 1. 第一项 | 有序列表 |
| 链接 | [文本](URL) | 可点击的链接 |
| 引用 | > 引用内容 | 引用块 |
| 表格 | | 列1 | 列2 | | 表格 |
流式输出
流式输出允许您实时接收 AI 的回复,提供更好的用户体验。
实现方式
在请求中设置 "stream": true,服务器将返回 Server-Sent Events (SSE) 格式的数据流。
处理流式响应
stream = client.chat.completions.create(
model="GCM-2",
messages=[{"role": "user", "content": "讲个故事"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Python 接入示例
推荐使用原生 requests 库进行调用。
pip install requests
import requests
import json
API_KEY = "sk-gcm-YOUR_KEY"
API_URL = "https://developer.maplegcm.com/v1/chat/completions"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
}
data = {
"model": "GCM-2",
"messages": [
{"role": "system", "content": "你是一个专业的助手。"},
{"role": "user", "content": "你好,请介绍一下你自己"}
],
"stream": True
}
# 发起流式请求
response = requests.post(API_URL, headers=headers, json=data, stream=True)
if response.status_code == 200:
for line in response.iter_lines():
if line:
line = line.decode('utf-8')
if line.startswith("data: "):
json_str = line[6:] # 去掉 'data: ' 前缀
if json_str == "[DONE]":
break
try:
chunk = json.loads(json_str)
if "content" in chunk["choices"][0]["delta"]:
print(chunk["choices"][0]["delta"]["content"], end="", flush=True)
except json.JSONDecodeError:
continue
else:
print(f"Error: {response.status_code} - {response.text}")
Node.js 接入示例
使用原生 fetch API (Node.js 18+)。
const API_KEY = 'sk-gcm-YOUR_KEY';
const API_URL = 'https://developer.maplegcm.com/v1/chat/completions';
async function main() {
const response = await fetch(API_URL, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
body: JSON.stringify({
model: 'GCM-2',
messages: [{ role: 'user', content: 'Hello world' }],
stream: true
})
});
if (!response.ok) {
console.error(`Error: ${response.status} ${response.statusText}`);
return;
}
// 处理流式响应
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
const lines = chunk.split('\n');
for (const line of lines) {
if (line.startsWith('data: ')) {
const jsonStr = line.slice(6);
if (jsonStr === '[DONE]') return;
try {
const data = JSON.parse(jsonStr);
const content = data.choices[0]?.delta?.content || '';
process.stdout.write(content);
} catch (e) {
// 忽略解析错误
}
}
}
}
}
main();
Go Lang 接入示例
使用标准库 net/http。
package main
import (
"bufio"
"bytes"
"encoding/json"
"fmt"
"net/http"
"strings"
)
type Message struct {
Role string `json:"role"`
Content string `json:"content"`
}
type ChatRequest struct {
Model string `json:"model"`
Messages []Message `json:"messages"`
Stream bool `json:"stream"`
}
type ChatResponseChunk struct {
Choices []struct {
Delta struct {
Content string `json:"content"`
} `json:"delta"`
} `json:"choices"`
}
func main() {
apiKey := "sk-gcm-YOUR_KEY"
url := "https://developer.maplegcm.com/v1/chat/completions"
reqBody, _ := json.Marshal(ChatRequest{
Model: "GCM-2",
Messages: []Message{
{Role: "user", Content: "Hello!"},
},
Stream: true,
})
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(reqBody))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
defer resp.Body.Close()
reader := bufio.NewReader(resp.Body)
for {
line, err := reader.ReadString('\n')
if err != nil {
break
}
line = strings.TrimSpace(line)
if strings.HasPrefix(line, "data: ") {
data := strings.TrimPrefix(line, "data: ")
if data == "[DONE]" {
break
}
var chunk ChatResponseChunk
if err := json.Unmarshal([]byte(data), &chunk); err == nil {
if len(chunk.Choices) > 0 {
fmt.Print(chunk.Choices[0].Delta.Content)
}
}
}
}
}
Java 接入示例
使用 java.net.http.HttpClient (Java 11+)。
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.stream.Stream;
public class Main {
public static void main(String[] args) {
String apiKey = "sk-gcm-YOUR_KEY";
String url = "https://developer.maplegcm.com/v1/chat/completions";
String jsonBody = "{"
+ "\"model\": \"GCM-2\","
+ "\"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],"
+ "\"stream\": true"
+ "}";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + apiKey)
.POST(BodyPublishers.ofString(jsonBody))
.build();
client.sendAsync(request, BodyHandlers.ofLines())
.thenAccept(response -> {
response.body().forEach(line -> {
if (line.startsWith("data: ")) {
String data = line.substring(6);
if (!"[DONE]".equals(data)) {
// 简单的字符串提取,实际项目中建议使用 Jackson/Gson
int contentIndex = data.indexOf("\"content\":");
if (contentIndex != -1) {
int start = contentIndex + 11;
int end = data.indexOf("\"", start);
if (end != -1) {
String content = data.substring(start, end);
// 处理转义字符
content = content.replace("\\n", "\n").replace("\\\"", "\"");
System.out.print(content);
}
}
}
}
});
})
.join(); // 等待完成
}
}
最佳实践
系统提示词设计
- 明确指定 AI 的角色和任务
- 要求使用 Markdown 格式输出(如适用)
- 设置输出长度限制(如"请用100字以内回答")
- 指定回答风格(如"专业"、"友好"、"简洁")
错误处理
- 始终检查 API 响应状态码
- 处理网络超时和重试逻辑
- 监控余额,避免因余额不足导致请求失败
- 记录错误日志以便调试
性能优化
- 使用流式输出提升用户体验
- 合理设置
temperature参数(创意任务用高值,精确任务用低值) - 缓存常见问题的回答
- 批量处理请求以提高效率
安全性
- 永远不要在客户端代码中暴露 API Key
- 使用环境变量存储密钥
- 定期轮换 API Key
- 监控异常使用情况
错误处理
了解常见的错误类型和解决方法。
HTTP 状态码
| 状态码 | 含义 | 解决方法 |
|---|---|---|
| 200 | 成功 | - |
| 400 | 请求参数错误 | 检查请求体格式和参数 |
| 401 | 认证失败 | 检查 API Key 是否正确 |
| 402 | 余额不足 | 前往控制台充值 |
| 429 | 请求频率过高 | 降低请求频率或联系支持 |
| 500 | 服务器错误 | 稍后重试或联系技术支持 |
错误响应格式
{
"error": {
"message": "Insufficient balance",
"type": "insufficient_balance",
"code": 402
}
}