在 Vercel AI SDK 中使用 GPTZZZ

先按模型选包

GPTZZZ 的每个 API Key 只属于一个分组，只能调用这个分组里的模型。先确定要调用的模型在哪个分组，再选 AI SDK 的包。

GPT 分组支持 /v1/chat/completions（含流式、工具调用、JSON 模式）和 /v1/responses。Claude 分组用 Claude Messages 接口。Gemini、DeepSeek、Grok、Qwen、MiMo 等其他分组可用哪些接口，以控制台和 API 文档为准，本页不给示例。GPTZZZ 暂不支持 embeddings，所以 AI SDK 的 embed() 用不了。

每个模型在哪些分组，见模型价格页的分组一览。

准备：Node.js、Key 与安装

1. Node.js 22 或更高。AI SDK 7 要求 Node.js 22+，并且只提供 ESM：package.json 里要有 "type": "module"。下面的 .ts 示例用了顶层 await，要按 ESM 运行。还在 Node.js 18、20 上的项目，见下文 AI SDK 6 一节。
2. 创建 Key。登录后在控制台 /keys 创建 API Key，创建时选择分组。要同时调用 GPT 和 Claude 模型，就为两个分组各建一个 Key，余额共用。
3. Key 只放服务端环境变量。不要写进前端代码或公开仓库。也不要放进 URL 查询参数：GPTZZZ 会拒绝查询参数里的 Key。

npm install ai @ai-sdk/openai-compatible

# 按需安装
npm install @ai-sdk/openai       # 走 Responses API
npm install @ai-sdk/anthropic    # 调用 Claude 分组的模型
npm install zod                  # 定义工具参数

# 直接运行 .ts 文件
npm install -D tsx typescript @types/node

export GPTZZZ_API_KEY="<YOUR_API_KEY>"

下面的示例都从 GPTZZZ_API_KEY 读 Key，每个示例注明需要哪个分组的 Key。同一个进程要同时用两个分组时，给第二个 Key 另起一个变量名，不要混用。

createOpenAICompatible：调用 GPT 模型

这是 AI SDK 文档给 OpenAI 兼容服务的通用接法。先建一个 provider，后面的示例都复用它：

// gptzzz.ts
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

export const gptzzz = createOpenAICompatible({
  name: 'gptzzz',
  baseURL: 'https://gptzzz.ai/v1',
  apiKey: process.env.GPTZZZ_API_KEY,
  includeUsage: true, // 流式响应也返回 token 用量
});

• baseURL 写到 /v1 为止。SDK 会自己追加 /chat/completions，写成 https://gptzzz.ai/v1/chat/completions 会让路径重复。
• apiKey 会放进 Authorization: Bearer 请求头。这个包不会自动读环境变量：GPTZZZ_API_KEY 没设置时，请求不带 Key，会被拒绝。
• name 是 provider 的名字，providerOptions 里用它作键。
• includeUsage 默认关闭。打开后，流式响应里也有 token 用量。

generateText 一次返回完整结果。需要 GPT 分组的 Key：

// generate.ts
import { generateText } from 'ai';
import { gptzzz } from './gptzzz';

const { text, usage } = await generateText({
  model: gptzzz('gpt-5.5'),
  instructions: '用中文回答，不超过两句话。',
  prompt: '什么是 API 网关？',
});

console.log(text);
console.log(usage.inputTokens, usage.outputTokens);

运行：npx tsx generate.ts。AI SDK 7 把系统提示的参数名从 system 改成了 instructions；system 仍可用，但已弃用。

streamText：流式输出

需要 GPT 分组的 Key：

// stream.ts
import { streamText } from 'ai';
import { gptzzz } from './gptzzz';

const result = streamText({
  model: gptzzz('gpt-5.5'),
  prompt: '从 1 数到 10，每行一个数字。',
  onError({ error }) {
    console.error(error);
  },
});

for await (const delta of result.textStream) {
  process.stdout.write(delta);
}

const usage = await result.usage;
console.log('\n', usage.inputTokens, usage.outputTokens);

• streamText 不抛出请求错误，错误会进入流里。默认只用 console.error 打印错误，textStream 直接结束，不输出文本。要自己记录或上报错误，传 onError。
• 流要被读完才会结束。result.usage 等结果在流结束后才有值。
• 拿不到用量时，检查 provider 是否设了 includeUsage: true。

流式事件、结束标记和工具调用怎么验收，见流式输出和工具调用的兼容性验收方法。

工具调用

需要 GPT 分组的 Key，另外安装 zod。execute 里换成你自己的查询逻辑：

// tools.ts
import { generateText, tool, isStepCount } from 'ai';
import { z } from 'zod';
import { gptzzz } from './gptzzz';

const { text, steps } = await generateText({
  model: gptzzz('gpt-5.5'),
  tools: {
    weather: tool({
      description: '查询城市当前气温',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, temperatureC: 22 }),
    }),
  },
  stopWhen: isStepCount(3),
  prompt: '上海现在多少度？',
});

console.log(steps.length, text);

• stopWhen: isStepCount(3) 让 SDK 在工具返回结果后继续请求模型，最多 3 步。AI SDK 6 里这个函数叫 stepCountIs。
• AI SDK 的 OpenAI provider 文档写明：GPT-6 及之后的模型做工具调用要用 Responses API。要用 gpt-6 系列模型调工具，改用下面的 @ai-sdk/openai。

Next.js 路由处理器

在 App Router 里，把模型调用放在服务端的路由处理器，Key 不会进浏览器。下面按 AI SDK 7 官方 Next.js App Router 快速入门的写法，只换了 provider。需要 GPT 分组的 Key：

// app/api/chat/route.ts
import {
  streamText,
  UIMessage,
  convertToModelMessages,
  createUIMessageStreamResponse,
  toUIMessageStream,
} from 'ai';
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

const gptzzz = createOpenAICompatible({
  name: 'gptzzz',
  baseURL: 'https://gptzzz.ai/v1',
  apiKey: process.env.GPTZZZ_API_KEY,
  includeUsage: true,
});

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: gptzzz('gpt-5.5'),
    messages: await convertToModelMessages(messages),
  });

  return createUIMessageStreamResponse({
    stream: toUIMessageStream({ stream: result.stream }),
  });
}

Key 写在项目根目录的 .env.local：

GPTZZZ_API_KEY=<YOUR_API_KEY>

前端用 @ai-sdk/react 的 useChat，页面代码照官方快速入门写即可。AI SDK 6 的 result.toUIMessageStreamResponse() 在 7 里已弃用，仍能用但会有警告。

走 Responses API：@ai-sdk/openai

GPT 分组也支持 /v1/responses。需要 Responses API 时，用 @ai-sdk/openai 的 createOpenAI，同样用 GPT 分组的 Key：

// responses.ts
import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const apiKey = process.env.GPTZZZ_API_KEY;
if (!apiKey) throw new Error('GPTZZZ_API_KEY 未设置');

const openai = createOpenAI({
  baseURL: 'https://gptzzz.ai/v1',
  apiKey,
});

const { text } = await generateText({
  model: openai('gpt-6-sol'), // 默认走 POST /v1/responses
  prompt: '用一句话解释什么是 API 网关。',
});

console.log(text);

• 从 AI SDK 5 起，openai('model-id') 默认调用 Responses API。openai.responses('model-id') 是显式写法，openai.chat('model-id') 走 Chat Completions。
• 不传 baseURL 时，它先读 OPENAI_BASE_URL，再退回 https://api.openai.com/v1。所以 baseURL 要显式写上。
• apiKey 是 undefined 时，它会改读 OPENAI_API_KEY。如果 GPTZZZ_API_KEY 没加载，而机器上设了 OpenAI 的 Key，这把 Key 会被发到 gptzzz.ai。所以示例先检查变量，再创建 provider。

怎么选：普通对话、流式和工具调用，用 createOpenAICompatible 就够了。要用 Responses API，或要用 gpt-6 系列模型调工具，选 @ai-sdk/openai。两种写法用同一个 GPT 分组的 Key。迁移时要比对的差异见 OpenAI 兼容 API 迁移。

调用 Claude 模型：@ai-sdk/anthropic

需要 Claude官key 分组的 Key。GPT 分组的 Key 调不了 Claude 模型。

// claude.ts
import { createAnthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const apiKey = process.env.GPTZZZ_API_KEY; // Claude官key 分组的 Key
if (!apiKey) throw new Error('GPTZZZ_API_KEY 未设置');

const anthropic = createAnthropic({
  baseURL: 'https://gptzzz.ai/v1',
  apiKey,
});

const { text } = await generateText({
  model: anthropic('claude-sonnet-5'),
  prompt: '用一句话解释什么是 API 网关。',
});

console.log(text);

• @ai-sdk/anthropic 的 baseURL 默认是 https://api.anthropic.com/v1，带 /v1，SDK 在后面追加 /messages。所以填 https://gptzzz.ai/v1，最终请求 https://gptzzz.ai/v1/messages。
• 这和 Claude Code 不同。Claude Code 的 ANTHROPIC_BASE_URL 填 https://gptzzz.ai，不带 /v1。
• 不传 baseURL 时，createAnthropic 会读 ANTHROPIC_BASE_URL 环境变量。如果你为 Claude Code 设过 ANTHROPIC_BASE_URL=https://gptzzz.ai，请求会变成 https://gptzzz.ai/messages。所以始终显式传 baseURL。
• apiKey 走 x-api-key 请求头。也可以改传 authToken，走 Authorization: Bearer。GPTZZZ 两种都接受，但两个参数不能同时传。
• apiKey 和 authToken 都没传（比如 GPTZZZ_API_KEY 没加载，apiKey 是 undefined）时，它会改读 ANTHROPIC_API_KEY，把那把 Key 发到 gptzzz.ai。所以示例先检查变量。

Claude Messages 的请求格式和流式事件见 Claude API 接入教程。

还在用 AI SDK 6

AI SDK 6 仍在发布维护版本，npm 上的 dist-tag 是 ai-v6，支持 Node.js 18+。GPTZZZ 的 provider 配置写法不变，只有几个 API 名称不同：

npm install ai@ai-v6 @ai-sdk/openai-compatible@ai-v6

# 按需安装
npm install @ai-sdk/openai@ai-v6      # 走 Responses API
npm install @ai-sdk/anthropic@ai-v6   # 调用 Claude 分组的模型

AI SDK 6 项目里，所有 @ai-sdk/* 包都要装 ai-v6 标签的版本：@ai-sdk/openai-compatible 2.x、@ai-sdk/openai 3.x、@ai-sdk/anthropic 3.x。混装 AI SDK 7 的 provider 包（@ai-sdk/openai 4.x 等），调用时会报 UnsupportedModelVersionError。

完整变更见 AI SDK 7 迁移指南。

常见报错

先拿到状态码和响应体，再对照下表。请求失败时 AI SDK 抛出 APICallError：

import { APICallError } from 'ai';

try {
  // generateText(...)
} catch (error) {
  if (APICallError.isInstance(error)) {
    console.error(error.statusCode, error.responseBody);
  }
}

更多状态码见 AI API 错误码速查手册。仍无法定位时，带上 UTC 时间、模型 ID、状态码和脱敏后的请求联系技术支持。

常见问题

相关链接

• GPTZZZ API 文档：接入参数与排错顺序
• 模型价格与分组
• OpenAI 兼容 API 迁移：Responses、Base URL 与回滚
• 流式输出和工具调用的兼容性验收方法
• AI SDK 官方文档：OpenAI Compatible Providers
• AI SDK 官方文档：OpenAI Provider
• AI SDK 官方文档：Anthropic Provider
• vercel/ai（GitHub）

说明：GPTZZZ 是独立的第三方 AI API 中转服务，不隶属于任何模型厂商；本页不是 Vercel 官方文档。模型、分组与价格以控制台和模型价格页为准。

不熟悉文中的概念？配合 AI API 术语表 一起看。