SDK PHP

A biblioteca PHP da Anthropic fornece acesso conveniente à Claude API a partir de qualquer aplicação PHP 8.1.0+.

Instalação

O SDK usa PSR-18 para HTTP e descobre automaticamente qualquer cliente PSR-18 instalado. O Guzzle é recomendado porque o SDK o configura para streaming sem nenhuma configuração adicional:

composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7"

Requisitos

PHP 8.1.0 ou superior.

Uso

Esta biblioteca usa parâmetros nomeados para especificar argumentos opcionais. Parâmetros com um valor padrão devem ser definidos pelo nome.

$client = new Client();

$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
);

$textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text');
echo $textBlock->text;

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação. Se sua chave de API for uma chave pessoal ou de conta de serviço com acesso a vários workspaces, defina o ID do workspace no cabeçalho de requisição anthropic-workspace-id; Selecionar um workspace mostra a opção por requisição para este SDK.

Objetos de valor

É recomendado usar o construtor estático with Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...) e parâmetros nomeados para inicializar "value objects" (objetos de valor).

No entanto, builders também são fornecidos (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").

Streaming

O SDK oferece suporte a respostas em streaming usando "Server-Sent Events" (eventos enviados pelo servidor), ou SSE.

$client = new Client();

$stream = $client->messages->createStream(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
);

foreach ($stream as $event) {
  echo $event->type . PHP_EOL;
}

O streaming requer um cliente HTTP que retorne o corpo da resposta de forma incremental. Quando o Guzzle é o cliente PSR-18 descoberto, o SDK o configura para streaming automaticamente. Com um cliente que faz buffering, o loop foreach produz todos os eventos de uma só vez quando a resposta é concluída, em vez de incrementalmente; se você observar esse sintoma, instale o Guzzle ou forneça um cliente PSR-18 com suporte a streaming por meio da opção de requisição streamingTransporter:

$client = new Anthropic\Client(
  requestOptions: Anthropic\RequestOptions::with(streamingTransporter: $myStreamingClient),
);

Tratamento de erros

Quando a biblioteca não consegue se conectar à API, ou se a API retorna um código de status que não indica sucesso (ou seja, uma resposta 4xx ou 5xx), uma subclasse de Anthropic\Core\Exceptions\APIException é lançada:

<?php
// ...
use Anthropic\Core\Exceptions\APIConnectionException;
use Anthropic\Core\Exceptions\APIStatusException;
use Anthropic\Core\Exceptions\RateLimitException;
// ...
try {
  $message = $client->messages->create(
    maxTokens: 1024,
    messages: [['role' => 'user', 'content' => 'Hello, Claude']],
    model: 'claude-opus-5',
  );
} catch (APIConnectionException $e) {
  echo "The server could not be reached", PHP_EOL;
  echo $e->getPrevious()?->getMessage(), PHP_EOL;
} catch (RateLimitException $_) {
  echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
} catch (APIStatusException $e) {
  echo "Another non-200-range status code was received", PHP_EOL;
  echo $e->getMessage();
}

Os códigos de erro são os seguintes:

Novas tentativas

Certos erros são automaticamente repetidos duas vezes por padrão, com um curto backoff exponencial.

Erros de conexão (por exemplo, devido a um problema de conectividade de rede), 408 Request Timeout, 409 Conflict, 429 Rate Limit, erros internos >=500 e timeouts são todos repetidos por padrão.

Você pode usar a opção maxRetries para configurar ou desativar isso:

use Anthropic\RequestOptions;
// ...
// Configure o padrão para todas as requisições:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// Ou configure por requisição:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

Paginação

Os métodos de listagem na Claude API são paginados.

Esta biblioteca fornece iteradores com paginação automática em cada resposta de listagem, para que você não precise solicitar páginas sucessivas manualmente:

$client = new Client();

$page = $client->beta->messages->batches->list(limit: 20);

// busca itens da página atual
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// faz requisições de rede adicionais para buscar itens de todas as páginas, incluindo a página atual e as seguintes
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}

Uso avançado

Propriedades não documentadas

Você pode enviar parâmetros não documentados para qualquer endpoint e ler propriedades de resposta não documentadas, da seguinte forma:

<?php
// ...
use Anthropic\RequestOptions;
// ...
$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
  requestOptions: RequestOptions::with(
    extraQueryParams: ['my_query_parameter' => 'value'],
    extraBodyParams: ['my_body_parameter' => 'value'],
    extraHeaders: ['my-header' => 'value'],
  ),
);

Parâmetros de requisição não documentados

Se você quiser enviar explicitamente um parâmetro extra, pode fazê-lo com as opções extraQueryParams, extraBodyParams e extraHeaders em RequestOptions::with() ao fazer uma requisição, como visto no exemplo anterior.

Endpoints não documentados

Para fazer requisições a endpoints não documentados mantendo o benefício de autenticação, novas tentativas e outros recursos do cliente, você pode fazer requisições usando client->request, da seguinte forma:

$client = new Client();

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);

Integrações com plataformas

O SDK PHP oferece suporte às seguintes plataformas:

• Agent Platform: Anthropic\Vertex\Client. Use ::fromEnvironment().
• Bedrock: Anthropic\Bedrock\MantleClient. Use new MantleClient(awsRegion: ...).
• Bedrock (legado): Anthropic\Bedrock\Client. Use ::fromEnvironment() ou ::withCredentials().
• Claude Platform na AWS: Anthropic\Aws\Client (requer aws/aws-sdk-php como dependência opcional). Use new Anthropic\Aws\Client(workspaceId: ...) ou defina ANTHROPIC_AWS_WORKSPACE_ID. Disponível em beta.
• Foundry: Anthropic\Foundry\Client. Use ::withCredentials().

Use MantleClient para novos projetos; Anthropic\Bedrock\Client permanece para aplicações existentes que usam a API InvokeModel do Bedrock.

Versionamento semântico

Este pacote segue as convenções do SemVer. Como a biblioteca está em desenvolvimento inicial e tem uma versão principal 0, as APIs podem mudar a qualquer momento.

Este pacote considera melhorias nas definições de tipo PHPDoc (não relacionadas ao tempo de execução) como alterações que não quebram compatibilidade.

Recursos adicionais

• Repositório no GitHub
• Packagist
• Referência da API
• Streaming de mensagens