MapleGCM API 开发文档

构建下一代 AI 应用的完整解决方案。我们的 API 旨在提供高性能、易集成的 AI 服务,帮助开发者快速构建智能应用。

基础 URL: https://developer.maplegcm.com/v1

认证鉴权

所有 API 请求都需要在 HTTP Header 中包含 Authorization 字段。

HTTP Header
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 模型。

POST /chat/completions

请求参数

参数类型必填说明
modelstring模型ID:GCM-2, GCM-2-SearchGCM-2-Thinking
messagesarray消息列表,每个消息包含 role (system/user/assistant) 和 content
streamboolean是否开启流式传输 (SSE),默认 true,推荐开启
temperaturenumber采样温度,范围 0-2,默认 0.7。值越高越随机

消息格式

每个消息对象包含以下字段:

  • role: "system"(系统提示)、"user"(用户消息)或 "assistant"(助手回复)
  • content: 消息内容(字符串)

请求示例

cURL
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) 格式,每个数据块格式如下:

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-Thinking 模型采用先进的思维链技术,在回答前会先输出思考过程。

返回格式

模型返回的内容将包含两个部分:思考过程和最终回答。

响应示例
<thinking>
这里是模型对于问题的深度分析和推理过程...
1. 分析问题核心...
2. 拆解逻辑步骤...
3. 验证推导结果...
</thinking>

这里是最终的回答结果。

建议在前端展示时,解析 <thinking> 标签,并将其渲染为可折叠的“思考过程”区域,以提供更好的用户体验。

Python 调用示例
# 使用 GCM-2-Thinking
response = client.chat.completions.create(
    model="GCM-2-Thinking",
    messages=[
        {"role": "user", "content": "请证明费马大定理"}
    ],
    stream=True
)

模型列表 (Models)

获取所有可用模型的列表。

GET /models

响应示例

JSON 响应
{
  "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
- 项目2
无序列表
有序列表1. 第一项
2. 第二项
有序列表
链接[文本](URL)可点击的链接
引用> 引用内容引用块
表格| 列1 | 列2 |
|---|---|
| 值1 | 值2 |
表格

流式输出

流式输出允许您实时接收 AI 的回复,提供更好的用户体验。

实现方式

在请求中设置 "stream": true,服务器将返回 Server-Sent Events (SSE) 格式的数据流。

处理流式响应

Python
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
Python 代码 (main.py)
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+)。

Node.js 代码 (index.mjs)
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

main.go
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+)。

Java 代码
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
  }
}