Project Icon

anthropic-sdk-typescript

简化 AI 对话开发的高效 TypeScript 接口

这个开源项目提供了一个 TypeScript API 库,用于简化 Anthropic REST API 的访问。该库支持服务器端 TypeScript 和 JavaScript,具有流式响应、错误处理和自定义请求等功能。它提供完整的类型定义,兼容多种运行时环境,方便开发者将 AI 对话功能集成到项目中。

Anthropic TypeScript API 库

NPM 版本 npm 包大小

该库为服务器端 TypeScript 或 JavaScript 提供了方便访问 Anthropic REST API 的功能。

REST API 文档可以在 docs.anthropic.com 上找到。本库的完整 API 可以在 api.md 中找到。

安装

npm install @anthropic-ai/sdk

使用

本库的完整 API 可以在 api.md 中找到。

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env['ANTHROPIC_API_KEY'], // 这是默认设置,可以省略
});

async function main() {
  const message = await client.messages.create({
    max_tokens: 1024,
    messages: [{ role: 'user', content: '你好,Claude' }],
    model: 'claude-3-opus-20240229',
  });

  console.log(message.content);
}

main();

流式响应

我们提供使用服务器发送事件(SSE)的流式响应支持。

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: 'user', content: '你好,Claude' }],
  model: 'claude-3-opus-20240229',
  stream: true,
});
for await (const messageStreamEvent of stream) {
  console.log(messageStreamEvent.type);
}

如果需要取消流,可以从循环中 break 或调用 stream.controller.abort()

请求和响应类型

本库包含所有请求参数和响应字段的 TypeScript 定义。您可以按以下方式导入和使用它们:

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env['ANTHROPIC_API_KEY'], // 这是默认设置,可以省略
});

async function main() {
  const params: Anthropic.MessageCreateParams = {
    max_tokens: 1024,
    messages: [{ role: 'user', content: '你好,Claude' }],
    model: 'claude-3-opus-20240229',
  };
  const message: Anthropic.Message = await client.messages.create(params);
}

main();

每个方法、请求参数和响应字段的文档都可以在文档字符串中找到,并会在大多数现代编辑器中悬停时显示。

计算令牌数

您可以通过 usage 响应属性查看特定请求的确切使用情况,例如:

const message = await client.messages.create(...)
console.log(message.usage)
// { input_tokens: 25, output_tokens: 13 }

流式处理辅助函数

本库为流式消息处理提供了几个便利功能,例如:

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

async function main() {
  const stream = anthropic.messages
    .stream({
      model: 'claude-3-opus-20240229',
      max_tokens: 1024,
      messages: [
        {
          role: 'user',
          content: '说你好!',
        },
      ],
    })
    .on('text', (text) => {
      console.log(text);
    });

  const message = await stream.finalMessage();
  console.log(message);
}

main();

使用 client.messages.stream(...) 进行流式处理会公开各种便利的辅助函数,包括事件处理程序和累积。

或者,您可以使用 client.messages.create({ ..., stream: true }),它只返回流中事件的异步迭代器,从而使用更少的内存(它不会为您构建最终的消息对象)。

工具使用测试版

本 SDK 为工具使用(也称为函数调用)提供测试版支持。更多详情可以在文档中找到。

AWS Bedrock

我们通过单独的包Anthropic Bedrock API 提供支持。

错误处理

当库无法连接到 API,或 API 返回非成功状态码(即 4xx 或 5xx 响应)时,将抛出 APIError 的子类:

async function main() {
  const message = await client.messages
    .create({
      max_tokens: 1024,
      messages: [{ role: 'user', content: '你好,Claude' }],
      model: 'claude-3-opus-20240229',
    })
    .catch(async (err) => {
      if (err instanceof Anthropic.APIError) {
        console.log(err.status); // 400
        console.log(err.name); // BadRequestError
        console.log(err.headers); // {server: 'nginx', ...}
      } else {
        throw err;
      }
    });
}

main();

错误代码如下:

状态码错误类型
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
422UnprocessableEntityError
429RateLimitError
>=500InternalServerError
N/AAPIConnectionError

重试

某些错误默认会自动重试 2 次,并使用短暂的指数退避。 连接错误(例如,由于网络连接问题)、408 请求超时、409 冲突、429 速率限制和 >=500 内部错误默认都会重试。

您可以使用 maxRetries 选项来配置或禁用此功能:

// 为所有请求配置默认值:
const client = new Anthropic({
  maxRetries: 0, // 默认为 2
});

// 或者,为每个请求单独配置:
await client.messages.create({ max_tokens: 1024, messages: [{ role: 'user', content: '你好,Claude' }], model: 'claude-3-opus-20240229' }, {
  maxRetries: 5,
});

超时

请求默认在 10 分钟后超时。您可以使用 timeout 选项来配置此设置:

// 为所有请求配置默认值:
const client = new Anthropic({
  timeout: 20 * 1000, // 20 秒(默认为 10 分钟)
});

// 为每个请求单独覆盖:
await client.messages.create({ max_tokens: 1024, messages: [{ role: 'user', content: '你好,Claude' }], model: 'claude-3-opus-20240229' }, {
  timeout: 5 * 1000,
});

超时时会抛出 APIConnectionTimeoutError

请注意,超时的请求默认会重试两次

默认标头

我们会自动发送 anthropic-version 标头,设置为 2023-06-01

如果需要,您可以在每个请求的基础上通过设置默认标头来覆盖它。

请注意,这样做可能会导致 SDK 中的类型不正确以及其他意外或未定义的行为。

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const message = await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: 'user', content: '你好,Claude' }],
    model: 'claude-3-opus-20240229',
  },
  { headers: { 'anthropic-version': '自定义值' } },
);

高级用法

访问原始响应数据(例如,标头)

可以通过所有方法返回的 APIPromise 类型上的 .asResponse() 方法访问 fetch() 返回的"原始" Response

您还可以使用 .withResponse() 方法同时获取原始 Response 和解析后的数据。

const client = new Anthropic();

const response = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: 'user', content: '你好,Claude' }],
    model: 'claude-3-opus-20240229',
  })
  .asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // 访问底层的 Response 对象

const { data: message, response: raw } = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: 'user', content: '你好,Claude' }],
    model: 'claude-3-opus-20240229',
  })
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(message.content);

发送自定义/未记录的请求

该库针对便捷访问已记录的 API 进行了类型化。如果您需要访问未记录的端点、参数或响应属性,仍可以使用该库。

未记录的端点

要向未记录的端点发送请求,您可以使用 client.getclient.post 和其他 HTTP 动词。 客户端上的选项(如重试)在发送这些请求时将被遵守。

await client.post('/some/path', {
  body: { some_prop: 'foo' },
  query: { some_query_arg: 'bar' },
});

未记录的请求参数

要使用未记录的参数发送请求,您可以在未记录的参数上使用 // @ts-expect-error。此库不会在运行时验证请求是否与类型匹配,因此您发送的任何额外值都将按原样发送。

client.foo.create({
  foo: 'my_param',
  bar: 12,
  // @ts-expect-error baz 尚未公开
  baz: '未记录的选项',
});

对于使用 GET 动词的请求,任何额外参数都将在查询中,所有其他请求都将在正文中发送额外参数。 如果你想显式地发送一个额外的参数,你可以使用 querybodyheaders 请求选项来实现。

未记录的响应属性

要访问未记录的响应属性,你可以在响应对象上使用 // @ts-expect-error 来访问响应对象,或者将响应对象转换为所需的类型。与请求参数一样,我们不会验证或去除 API 响应中的额外属性。

自定义 fetch 客户端

默认情况下,这个库在 Node 环境中使用 node-fetch,在其他环境中则期望有一个全局的 fetch 函数。

如果你更喜欢在 Node 环境中使用全局的、符合 Web 标准的 fetch 函数(例如,如果你使用 --experimental-fetch 运行 Node 或者使用 NextJS 这样用 undici 进行 polyfill 的框架),请在你第一次 from "Anthropic" 导入之前添加以下导入:

// 告诉 TypeScript 和包使用全局 Web fetch 而不是 node-fetch。
// 注意,尽管名字如此,这并不添加任何 polyfills,而是期望在需要时提供它们。
import '@anthropic-ai/sdk/shims/web';
import Anthropic from '@anthropic-ai/sdk';

要做相反的操作,添加 import "@anthropic-ai/sdk/shims/node"(这会导入 polyfills)。 如果你得到了错误的 Response TypeScript 类型,这也会很有用(更多详情)。

日志记录和中间件

你还可以在实例化客户端时提供一个自定义的 fetch 函数,用于在每个请求之前/之后检查或修改 RequestResponse

import { fetch } from 'undici'; // 这只是一个例子
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  fetch: async (url: RequestInfo, init?: RequestInit): Promise<Response> => {
    console.log('即将发起请求', url, init);
    const response = await fetch(url, init);
    console.log('收到响应', response);
    return response;
  },
});

注意,如果设置了 DEBUG=true 环境变量,这个库会自动记录所有请求和响应。这仅用于调试目的,可能会在未来不经通知就发生变化。

配置 HTTP(S) 代理(例如,用于代理)

默认情况下,这个库为所有 http/https 请求使用一个稳定的代理来重用 TCP 连接,消除了许多 TCP 和 TLS 握手,为大多数请求节省了大约 100ms。

如果你想禁用或自定义这种行为,例如在代理后面使用 API,你可以传递一个 httpAgent,它会用于所有请求(无论是 http 还是 https),例如:

import http from 'http';
import { HttpsProxyAgent } from 'https-proxy-agent';

// 为所有请求配置默认设置:
const client = new Anthropic({
  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
});

// 针对每个请求进行覆盖:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: 'user', content: '你好,Claude' }],
    model: 'claude-3-opus-20240229',
  },
  {
    httpAgent: new http.Agent({ keepAlive: false }),
  },
);

语义化版本

这个包通常遵循 SemVer 约定,尽管某些向后不兼容的更改可能会作为次要版本发布:

  1. 只影响静态类型的更改,不会破坏运行时行为。
  2. 对库内部的更改,这些内部技术上是公开的,但并不打算或记录供外部使用。(如果你依赖这些内部功能,请在 GitHub 上开一个 issue 告诉我们)。
  3. 我们预计不会影响绝大多数用户的更改。

我们非常重视向后兼容性,并努力确保你可以依赖平滑的升级体验。

我们很乐意听取你的反馈;请就问题、bug 或建议在 GitHub 上开一个 issue。

要求

支持 TypeScript >= 4.5。

支持以下运行时环境:

  • Node.js 18 LTS 或更高版本(非 EOL)。
  • Deno v1.28.0 或更高版本,使用 import Anthropic from "npm:@anthropic-ai/sdk"
  • Bun 1.0 或更高版本。
  • Cloudflare Workers。
  • Vercel Edge Runtime。
  • Jest 28 或更高版本,使用 "node" 环境(目前不支持 "jsdom")。
  • Nitro v2.6 或更高版本。

[!警告] 不支持 Web 浏览器运行时。如果在浏览器环境中使用,SDK 将抛出错误。

注意,目前不支持 React Native。

如果你对其他运行时环境感兴趣,请在 GitHub 上开一个 issue 或为现有的 issue 投票。

项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

问小白

问小白是一个基于 DeepSeek R1 模型的智能对话平台,专为用户提供高效、贴心的对话体验。实时在线,支持深度思考和联网搜索。免费不限次数,帮用户写作、创作、分析和规划,各种任务随时完成!

Project Cover

白日梦AI

白日梦AI提供专注于AI视频生成的多样化功能,包括文生视频、动态画面和形象生成等,帮助用户快速上手,创造专业级内容。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

讯飞绘镜

讯飞绘镜是一个支持从创意到完整视频创作的智能平台,用户可以快速生成视频素材并创作独特的音乐视频和故事。平台提供多样化的主题和精选作品,帮助用户探索创意灵感。

Project Cover

讯飞文书

讯飞文书依托讯飞星火大模型,为文书写作者提供从素材筹备到稿件撰写及审稿的全程支持。通过录音智记和以稿写稿等功能,满足事务性工作的高频需求,帮助撰稿人节省精力,提高效率,优化工作与生活。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

Trae

Trae是一种自适应的集成开发环境(IDE),通过自动化和多元协作改变开发流程。利用Trae,团队能够更快速、精确地编写和部署代码,从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能,是提升开发效率的理想工具。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号