SDK de PHP

La biblioteca de PHP de Anthropic proporciona acceso conveniente a la API REST de Anthropic desde cualquier aplicación PHP 8.1.0+.

Instalación

El SDK usa PSR-18 para HTTP y detecta automáticamente cualquier cliente PSR-18 instalado. Se recomienda Guzzle porque el SDK lo configura para streaming sin necesidad de configuración adicional:

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

Requisitos

PHP 8.1.0 o superior.

Uso

Esta biblioteca usa parámetros nombrados para especificar argumentos opcionales. Los parámetros con un valor predeterminado deben establecerse por nombre.

$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 conocer las opciones de autenticación, incluida Workload Identity Federation, consulta Autenticación.

Objetos de valor

Se recomienda usar el constructor estático with, Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...), y parámetros nombrados para inicializar objetos de valor.

Sin embargo, también se proporcionan builders: (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").

Streaming

El SDK proporciona soporte para respuestas en streaming usando "Server-Sent Events" (eventos enviados por el servidor), o 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;
}

El streaming requiere un cliente HTTP que devuelva el cuerpo de la respuesta de forma incremental. Cuando Guzzle es el cliente PSR-18 detectado, el SDK lo configura automáticamente para streaming. Con un cliente que almacena en búfer, el bucle foreach entrega todos los eventos de una sola vez cuando la respuesta se completa en lugar de hacerlo de forma incremental; si observas ese síntoma, instala Guzzle o proporciona un cliente PSR-18 compatible con streaming a través de la opción de solicitud streamingTransporter:

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

Manejo de errores

Cuando la biblioteca no puede conectarse a la API, o si la API devuelve un código de estado no exitoso (es decir, una respuesta 4xx o 5xx), se lanza una subclase de Anthropic\Core\Exceptions\APIException:

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

Los códigos de error son los siguientes:

Reintentos

Ciertos errores se reintentan automáticamente dos veces de forma predeterminada, con un breve retroceso exponencial.

Los errores de conexión (por ejemplo, debido a un problema de conectividad de red), 408 Request Timeout, 409 Conflict, 429 Rate Limit, errores internos >=500 y los tiempos de espera agotados se reintentan de forma predeterminada.

Puedes usar la opción maxRetries para configurar o deshabilitar esto:

use Anthropic\RequestOptions;
// ...
// Configura el valor predeterminado para todas las solicitudes:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// O bien, configura por solicitud:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-8',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

Paginación

Los métodos de listado en la API de Claude están paginados.

Esta biblioteca proporciona iteradores de paginación automática con cada respuesta de listado, por lo que no tienes que solicitar páginas sucesivas manualmente:

$client = new Client();

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

// obtén los elementos de la página actual
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// realiza solicitudes de red adicionales para obtener elementos de todas las páginas, incluida la actual y las siguientes
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}

Uso avanzado

Propiedades no documentadas

Puedes enviar parámetros no documentados a cualquier endpoint y leer propiedades de respuesta no documentadas, de la siguiente manera:

<?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 solicitud no documentados

Si deseas enviar explícitamente un parámetro adicional, puedes hacerlo con las opciones extraQueryParams, extraBodyParams y extraHeaders dentro de RequestOptions::with() al realizar una solicitud, como se muestra en el ejemplo anterior.

Endpoints no documentados

Para realizar solicitudes a endpoints no documentados conservando el beneficio de la autenticación, los reintentos y otras funcionalidades del cliente, puedes realizar solicitudes usando client->request, de la siguiente manera:

$client = new Client();

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

Integraciones de plataforma

El SDK de PHP es compatible con las siguientes plataformas:

• Bedrock: Anthropic\Bedrock\MantleClient. Usa new MantleClient(awsRegion: ...).
• Bedrock (legacy): Anthropic\Bedrock\Client. Usa ::fromEnvironment() o ::withCredentials().
• Vertex AI: Anthropic\Vertex\Client. Usa ::fromEnvironment().
• Foundry: Anthropic\Foundry\Client. Usa ::withCredentials().
• Claude Platform en AWS: Anthropic\Aws\Client (requiere aws/aws-sdk-php como dependencia opcional). Usa new Anthropic\Aws\Client(workspaceId: ...) o establece ANTHROPIC_AWS_WORKSPACE_ID. Disponible en beta.

Usa MantleClient para proyectos nuevos; Anthropic\Bedrock\Client se mantiene para aplicaciones existentes que usan la API InvokeModel de Bedrock.

Versionado semántico

Este paquete sigue las convenciones de SemVer. Dado que la biblioteca está en desarrollo inicial y tiene una versión mayor de 0, las APIs podrían cambiar en cualquier momento.

Este paquete considera que las mejoras a las definiciones de tipos de PHPDoc (que no son de tiempo de ejecución) son cambios no disruptivos.

Recursos adicionales

• Repositorio de GitHub
• Packagist
• Referencia de la API
• Mensajes en streaming