Anthropic TypeScript API 库

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();

错误代码如下：

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

重试

某些错误默认会自动重试 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.get、client.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 动词的请求，任何额外参数都将在查询中，所有其他请求都将在正文中发送额外参数。如果你想显式地发送一个额外的参数，你可以使用 query、body 和 headers 请求选项来实现。

未记录的响应属性

要访问未记录的响应属性，你可以在响应对象上使用 // @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 函数，用于在每个请求之前/之后检查或修改 Request 或 Response：

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 }),
  },
);