SDK para PHP

A biblioteca PHP da Anthropic fornece acesso conveniente à API REST da Anthropic 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 por nome.

$client = new Client();

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

echo $message->content[0]->text;

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação.

Value objects

Recomenda-se usar o construtor estático with, como em 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 para 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-4-8',
);

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 automaticamente para streaming. Com um cliente que usa buffer, o loop foreach produz todos os eventos de uma 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 através 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 de não 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-4-8',
  );
} 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 desabilitar 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-4-8',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

Paginação

Os métodos de listagem na API do Claude 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 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-4-8',
  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 de plataforma

O SDK para PHP oferece suporte às seguintes plataformas:

• Bedrock: Anthropic\Bedrock\MantleClient. Use new MantleClient(awsRegion: ...).
• Bedrock (legado): Anthropic\Bedrock\Client. Use ::fromEnvironment() ou ::withCredentials().
• Vertex AI: Anthropic\Vertex\Client. Use ::fromEnvironment().
• Foundry: Anthropic\Foundry\Client. Use ::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.

Use MantleClient para novos projetos; Anthropic\Bedrock\Client permanece disponível 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 (que não afetam o tempo de execução) como alterações não disruptivas.

Recursos adicionais

• Repositório no GitHub
• Packagist
• Referência da API
• Mensagens em streaming