# AI Provider API Integration

> ai-provider-api-integration

- Skill: `tybiefh-beep/ai-provider-api-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tybiefh-beep/ai-provider-api-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tybiefh-beep/ai-provider-api-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tybiefh-beep (https://skillmd.com/u/tybiefh-beep)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tybiefh-beep/ai-provider-api-integration

---


# ai-provider-api-integration

## 触发条件

需要在前端直接调用多家 AI 提供商 REST API 时使用。包括 Anthropic / OpenAI 兼容格式 / Gemini 特殊格式的请求构建、响应解析、错误处理、API Key 的浏览器端安全存储,以及模型可用性实时验证。

## 反触发(不适用)

- 后端代理架构下不使用(API Key 应放服务端)
- 仅调用单一提供商时过度设计(直接 fetch 即可)
- 涉及流式输出(SSE)时需另行处理
- 企业级生产环境(应走官方 SDK + 监控)

## Gotchas(易错点)

- **Anthropic 用 `x-api-key` header,OpenAI 用 `Authorization: Bearer`** → 抽象成 `buildHeaders(provider, key)`,别让业务层关心
- **Gemini 把 key 塞 query string** → `?key=xxx`,不是 header;同时 `safetySettings` 数组结构跟另两家完全不同
- **Anthropic 的 system 参数是顶层,OpenAI 是 messages[0].role='system'** → 别混
- **Anthropic 返回 content 是数组** → `response.content[0].text`;OpenAI 是 `response.choices[0].message.content`;Gemini 是 `response.candidates[0].content.parts[0].text`
- **流式 vs 非流式 content 路径不同** → 非流式直接读 `.content`;流式要 `ReadableStream` 读 `data: {...}\n\n` 增量拼
- **错误信息三家人结构差很大** → 统一抽象 `parseError(provider, status, body)` → 返回 `{ code, message, retryable }`
- **API Key 放 localStorage 已被同源脚本可读** → 接受这个限制(浏览器没更安全方案),但加 domain 校验和 CSP 头防 XSS 偷
- **CORS 跨域**:Anthropic 允许 `anthropic-dangerous-direct-browser-access: true` header(2024 年新增),OpenAI 默认不允许,需代理

## 覆盖操作(必须支持)

- [ ] Provider 配置对象设计(URL / header style / body schema / response path)
- [ ] headers 构建(按 provider 分发)
- [ ] buildBody 差异处理(Anthropic vs OpenAI vs Gemini)
- [ ] parseReply 统一抽象(三家不同返回路径 → 统一 string 输出)
- [ ] verifyModel 最小 token 验证(发"hi"看是否 200)
- [ ] localStorage 持久化 + 加密(可选 AES,key 由用户密码派生)
- [ ] 模型版本列表维护(推荐/预览/旧版标注)
- [ ] 错误重试策略(429/5xx 指数退避,4xx 直接报错)
- [ ] Token 用量统计(从 response.usage 提取)

## 工作流(分阶段)

### 1. 立项
- 列出要支持的 provider(2-8 家为宜)
- 决定是否流式(SSE)
- 决定是否多模态(图/文/音)

### 2. 数据设计
- Provider 配置:`{ id, name, baseUrl, authStyle, requestSchema, responseSchema, models[] }`
- 统一请求接口:`{ provider, model, messages, system, temperature, maxTokens, stream }`
- 统一响应接口:`{ content, usage, model, raw }`

### 3. 实现
- Provider 注册表(数组,新增 provider 加一项即可)
- `dispatch(provider, request)` 单一入口
- 三家 SDK 调用代码各放一个文件,业务层不感知差异
- 错误归一化(用户只看到"调用失败"+"原始错误")

### 4. 测试
- 每个 provider 至少 1 个正常调用 + 1 个错误路径
- Key 失效 → UI 明确提示
- 跨域失败 → 提示需要代理
- 流式中断 → 友好降级到非流式

## 交付清单(checklist)

- [ ] 至少支持 2-3 家 provider
- [ ] Provider 注册表化(新增 1 家 ≤ 50 行代码)
- [ ] 统一请求/响应接口
- [ ] verifyModel 一键验证
- [ ] API Key localStorage 存储 + 加密可选
- [ ] 错误信息用户友好(不暴露 stack)
- [ ] 模型版本可维护(推荐/预览/旧版标注)
- [ ] 至少 1 个 provider 流式输出