Vercel AI SDK

Vercel AI SDK 是用 TypeScript 打造 AI 功能的主流工具包。把它的 @ai-sdk/openai-compatible provider 指向 Synthorai,整個模型目錄就能用同一把 key 存取,Claude、GPT、Gemini 與開源權重系列並存。

開始之前

在 控制台 → API Keys. 建立一把 API key,建立後立即複製——它只會顯示一次。

第一步 — 安裝依賴

npm i ai @ai-sdk/openai-compatible

Synthorai 說的是 OpenAI Chat Completions 協定,所以不需要任何 Synthorai 專用套件——官方的 OpenAI 相容 provider 就是受支援的接入方式。

第二步 — 建立 provider 實例

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

const synthorai = createOpenAICompatible({
  name: 'synthorai',
  baseURL: 'https://synthorai.io/v1',
  apiKey: process.env.SYNTHORAI_API_KEY,
});

這裡的 name 只是鏈路追蹤和錯誤訊息裡的標籤,不影響路由。路由由 baseURL 和你傳入的模型 ID 決定。

⚠

base URL 必須以 /v1. 結尾。provider 會在後面拼接 /chat/completions 這類路徑,漏了它就會請求到錯誤位址。

第三步 — 生成與串流輸出

import { generateText } from 'ai';

const { text } = await generateText({
  model: synthorai('claude-sonnet-5-5'),
  prompt: 'Tell me about yourself in one sentence.',
});

console.log(text);

第一個參數是目錄裡的模型 ID。串流輸出用同一個 provider 實例,不需要額外設定:

import { streamText } from 'ai';

const result = streamText({
  model: synthorai('claude-sonnet-5-5'),
  prompt: 'Write a short haiku about routing.',
});

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

怎麼選模型

目錄裡的任何模型 ID 都可以用,下面是幾個穩妥的預設選擇:

參數	類型	說明
`claude-opus-5-5`	`agentic`	長會話 agent 任務和程式碼編輯的穩妥選擇。
`gpt-5.4`	`reasoning`	混合負載下的通用推理。
`gpt-5.4-mini`	`fast`	快且便宜,適合分類和短輸出。
`deepseek-v4-flash`	`cheapest`	目錄中價格最低的一檔模型之一,適合大批量調用。

改用 Anthropic 協定面

同一把 key 也在另一個路徑上提供 Anthropic Messages 協定,AI SDK 透過它的 Anthropic provider 存取。需要 Anthropic 原生特性時用它,其餘情況用上面的 OpenAI 相容 provider。

import { createAnthropic } from '@ai-sdk/anthropic';

const synthoraiAnthropic = createAnthropic({
  baseURL: 'https://synthorai.io/v1',
  apiKey: process.env.SYNTHORAI_API_KEY,
});

⚠

注意它和原生 Anthropic SDK 的區別:原生 SDK 收的是主機根位址、由它自己拼上 /v1/messages,而 AI SDK 的 Anthropic provider 要的是已經含 /v1 的前綴。這裡只填主機名會請求到錯誤路徑。

排錯

每次調用都 404。 base URL 必須以 /v1. 結尾。provider 會在後面拼接 /chat/completions 這類路徑,漏了它就會請求到錯誤位址。

401 未授權。 環境變數是在模組載入時讀的,行程啟動之後才 export 的 key 不會生效。設完重啟行程。

找不到模型。 模型 ID 區分大小寫,必須和目錄完全一致。用下面這條列出你這把 key 能存取的模型: curl https://synthorai.io/v1/models -H "Authorization: Bearer $SYNTHORAI_API_KEY"

所有模型 ID 和對應價格都列在 model price comparison 裡。