CLI, SDK 및 라이브러리클라이언트 SDK

PHP SDK

값 객체와 빌더 패턴을 사용하여 Anthropic PHP SDK를 설치하고 구성합니다

Anthropic PHP 라이브러리는 PHP 8.1.0 이상의 모든 애플리케이션에서 Anthropic REST API에 편리하게 접근할 수 있도록 지원합니다.

PHP SDK는 현재 베타 버전입니다. 버전 간에 API가 변경될 수 있습니다.

코드 예제가 포함된 API 기능 문서는 API 레퍼런스를 참조하세요. 이 페이지에서는 PHP 전용 SDK 기능 및 구성을 다룹니다.

설치

이 SDK는 HTTP를 위해 PSR-18을 사용하며 설치된 PSR-18 클라이언트를 자동으로 감지합니다. SDK가 추가 설정 없이 스트리밍을 위해 구성하므로 Guzzle 사용을 권장합니다:

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

요구 사항

PHP 8.1.0 이상.

사용법

이 라이브러리는 선택적 인수를 지정하기 위해 명명된 매개변수를 사용합니다. 기본값이 있는 매개변수는 이름으로 설정해야 합니다.

$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;

Workload Identity Federation을 포함한 인증 옵션에 대해서는 인증을 참조하세요.

값 객체

값 객체를 초기화할 때는 정적 with 생성자 Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...)와 명명된 매개변수를 사용하는 것을 권장합니다.

하지만 빌더도 제공됩니다: (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").

스트리밍

SDK는 "Server-Sent Events"(서버 전송 이벤트), 즉 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;
}

스트리밍에는 응답 본문을 점진적으로 반환하는 HTTP 클라이언트가 필요합니다. Guzzle이 감지된 PSR-18 클라이언트인 경우, SDK는 자동으로 스트리밍을 위해 구성합니다. 버퍼링 클라이언트를 사용하면 foreach 루프가 점진적으로 이벤트를 생성하는 대신 응답이 완료될 때 모든 이벤트를 한 번에 생성합니다. 이러한 증상이 관찰되면 Guzzle을 설치하거나 streamingTransporter 요청 옵션을 통해 스트리밍을 지원하는 PSR-18 클라이언트를 제공하세요:

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

오류 처리

라이브러리가 API에 연결할 수 없거나 API가 성공이 아닌 상태 코드(즉, 4xx 또는 5xx 응답)를 반환하는 경우, 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();
}

오류 코드는 다음과 같습니다:

원인	오류 유형
HTTP 400	`BadRequestException`
HTTP 401	`AuthenticationException`
HTTP 403	`PermissionDeniedException`
HTTP 404	`NotFoundException`
HTTP 409	`ConflictException`
HTTP 422	`UnprocessableEntityException`
HTTP 429	`RateLimitException`
HTTP >= 500	`InternalServerException`
기타 HTTP 오류	`APIStatusException`
타임아웃	`APITimeoutException`
네트워크 오류	`APIConnectionException`

재시도

특정 오류는 기본적으로 짧은 지수 백오프(exponential backoff)와 함께 자동으로 두 번 재시도됩니다.

연결 오류(예: 네트워크 연결 문제로 인한 오류), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 내부 오류 및 타임아웃은 모두 기본적으로 재시도됩니다.

maxRetries 옵션을 사용하여 이를 구성하거나 비활성화할 수 있습니다:

use Anthropic\RequestOptions;
// ...
// 모든 요청에 대한 기본값을 구성합니다:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// 또는 요청별로 구성합니다:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-8',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

페이지네이션

Claude API의 목록 메서드는 페이지네이션됩니다.

이 라이브러리는 각 목록 응답과 함께 자동 페이지네이션 반복자를 제공하므로 후속 페이지를 수동으로 요청할 필요가 없습니다:

$client = new Client();

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

// 현재 페이지에서 항목 가져오기
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// 현재 페이지를 포함하여 이후 모든 페이지에서 항목을 가져오기 위해 추가 네트워크 요청 수행
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}

고급 사용법

문서화되지 않은 속성

다음과 같이 문서화되지 않은 매개변수를 모든 엔드포인트로 전송하고 문서화되지 않은 응답 속성을 읽을 수 있습니다:

동일한 이름의 extra* 매개변수는 문서화된 매개변수를 재정의합니다.

<?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'],
  ),
);

문서화되지 않은 요청 매개변수

추가 매개변수를 명시적으로 전송하려면 앞의 예제에서 볼 수 있듯이 요청 시 RequestOptions::with() 아래의 extraQueryParams, extraBodyParams, extraHeaders 옵션을 사용할 수 있습니다.

문서화되지 않은 엔드포인트

인증, 재시도 및 기타 클라이언트 기능의 이점을 유지하면서 문서화되지 않은 엔드포인트에 요청하려면 다음과 같이 client->request를 사용하여 요청할 수 있습니다:

$client = new Client();

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

플랫폼 통합

코드 예제가 포함된 자세한 플랫폼 설정 가이드는 다음을 참조하세요:

PHP SDK는 다음 플랫폼을 지원합니다:

Bedrock: Anthropic\Bedrock\MantleClient. new MantleClient(awsRegion: ...)를 사용하세요.
Bedrock (레거시): Anthropic\Bedrock\Client. ::fromEnvironment() 또는 ::withCredentials()를 사용하세요.
Vertex AI: Anthropic\Vertex\Client. ::fromEnvironment()를 사용하세요.
Foundry: Anthropic\Foundry\Client. ::withCredentials()를 사용하세요.
AWS의 Claude Platform: Anthropic\Aws\Client (소프트 종속성으로 aws/aws-sdk-php 필요). new Anthropic\Aws\Client(workspaceId: ...)를 사용하거나 ANTHROPIC_AWS_WORKSPACE_ID를 설정하세요. 베타로 제공됩니다.

새 프로젝트에는 MantleClient를 사용하세요. Anthropic\Bedrock\Client는 Bedrock InvokeModel API를 사용하는 기존 애플리케이션을 위해 유지됩니다.

시맨틱 버저닝

이 패키지는 SemVer 규칙을 따릅니다. 라이브러리가 초기 개발 단계에 있고 주 버전이 0이므로 API는 언제든지 변경될 수 있습니다.

이 패키지는 (런타임이 아닌) PHPDoc 타입 정의의 개선을 호환성을 깨뜨리지 않는 변경으로 간주합니다.

추가 리소스

Was this page helpful?

CLI, SDK 및 라이브러리클라이언트 SDK

PHP SDK

값 객체와 빌더 패턴을 사용하여 Anthropic PHP SDK를 설치하고 구성합니다

Anthropic PHP 라이브러리는 PHP 8.1.0 이상의 모든 애플리케이션에서 Anthropic REST API에 편리하게 접근할 수 있도록 지원합니다.

PHP SDK는 현재 베타 버전입니다. 버전 간에 API가 변경될 수 있습니다.

코드 예제가 포함된 API 기능 문서는 API 레퍼런스를 참조하세요. 이 페이지에서는 PHP 전용 SDK 기능 및 구성을 다룹니다.

설치

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

요구 사항

PHP 8.1.0 이상.

사용법

이 라이브러리는 선택적 인수를 지정하기 위해 명명된 매개변수를 사용합니다. 기본값이 있는 매개변수는 이름으로 설정해야 합니다.

$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;

Workload Identity Federation을 포함한 인증 옵션에 대해서는 인증을 참조하세요.

값 객체

값 객체를 초기화할 때는 정적 with 생성자 Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...)와 명명된 매개변수를 사용하는 것을 권장합니다.

하지만 빌더도 제공됩니다: (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").

스트리밍

SDK는 "Server-Sent Events"(서버 전송 이벤트), 즉 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;
}

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

오류 처리

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

오류 코드는 다음과 같습니다:

원인	오류 유형
HTTP 400	`BadRequestException`
HTTP 401	`AuthenticationException`
HTTP 403	`PermissionDeniedException`
HTTP 404	`NotFoundException`
HTTP 409	`ConflictException`
HTTP 422	`UnprocessableEntityException`
HTTP 429	`RateLimitException`
HTTP >= 500	`InternalServerException`
기타 HTTP 오류	`APIStatusException`
타임아웃	`APITimeoutException`
네트워크 오류	`APIConnectionException`

재시도

특정 오류는 기본적으로 짧은 지수 백오프(exponential backoff)와 함께 자동으로 두 번 재시도됩니다.

연결 오류(예: 네트워크 연결 문제로 인한 오류), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 내부 오류 및 타임아웃은 모두 기본적으로 재시도됩니다.

maxRetries 옵션을 사용하여 이를 구성하거나 비활성화할 수 있습니다:

use Anthropic\RequestOptions;
// ...
// 모든 요청에 대한 기본값을 구성합니다:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// 또는 요청별로 구성합니다:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-8',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

페이지네이션

Claude API의 목록 메서드는 페이지네이션됩니다.

이 라이브러리는 각 목록 응답과 함께 자동 페이지네이션 반복자를 제공하므로 후속 페이지를 수동으로 요청할 필요가 없습니다:

$client = new Client();

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

// 현재 페이지에서 항목 가져오기
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// 현재 페이지를 포함하여 이후 모든 페이지에서 항목을 가져오기 위해 추가 네트워크 요청 수행
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}

고급 사용법

문서화되지 않은 속성

다음과 같이 문서화되지 않은 매개변수를 모든 엔드포인트로 전송하고 문서화되지 않은 응답 속성을 읽을 수 있습니다:

동일한 이름의 extra* 매개변수는 문서화된 매개변수를 재정의합니다.

<?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'],
  ),
);

문서화되지 않은 요청 매개변수

문서화되지 않은 엔드포인트

$client = new Client();

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

플랫폼 통합

코드 예제가 포함된 자세한 플랫폼 설정 가이드는 다음을 참조하세요:

PHP SDK는 다음 플랫폼을 지원합니다:

Bedrock: Anthropic\Bedrock\MantleClient. new MantleClient(awsRegion: ...)를 사용하세요.
Bedrock (레거시): Anthropic\Bedrock\Client. ::fromEnvironment() 또는 ::withCredentials()를 사용하세요.
Vertex AI: Anthropic\Vertex\Client. ::fromEnvironment()를 사용하세요.
Foundry: Anthropic\Foundry\Client. ::withCredentials()를 사용하세요.
AWS의 Claude Platform: Anthropic\Aws\Client (소프트 종속성으로 aws/aws-sdk-php 필요). new Anthropic\Aws\Client(workspaceId: ...)를 사용하거나 ANTHROPIC_AWS_WORKSPACE_ID를 설정하세요. 베타로 제공됩니다.

새 프로젝트에는 MantleClient를 사용하세요. Anthropic\Bedrock\Client는 Bedrock InvokeModel API를 사용하는 기존 애플리케이션을 위해 유지됩니다.

시맨틱 버저닝

이 패키지는 SemVer 규칙을 따릅니다. 라이브러리가 초기 개발 단계에 있고 주 버전이 0이므로 API는 언제든지 변경될 수 있습니다.

이 패키지는 (런타임이 아닌) PHPDoc 타입 정의의 개선을 호환성을 깨뜨리지 않는 변경으로 간주합니다.

추가 리소스

Was this page helpful?