Package: anthropic
Anthropic Python API libraryThe Anthropic Python library provides convenient access to the Anthropic REST API from any Python 3.7+
application. It includes type definitions for all request params and response fields,
and offers both synchronous and asynchronous clients powered byhttpx.For the AWS Bedrock API, seeanthropic-bedrock.DocumentationThe REST API documentation can be foundon docs.anthropic.com. The full API of this library can be found inapi.md.InstallationpipinstallanthropicUsageThe full API of this library can be found inapi.md.importosfromanthropicimportAnthropicclient=Anthropic(# This is the default and can be omittedapi_key=os.environ.get("ANTHROPIC_API_KEY"),)message=client.messages.create(max_tokens=1024,messages=[{"role":"user","content":"How does a court case get to the supreme court?",}],model="claude-2.1",)print(message.content)While you can provide anapi_keykeyword argument,
we recommend usingpython-dotenvto addANTHROPIC_API_KEY="my-anthropic-api-key"to your.envfile
so that your API Key is not stored in source control.Async usageSimply importAsyncAnthropicinstead ofAnthropicand useawaitwith each API call:importosimportasynciofromanthropicimportAsyncAnthropicclient=AsyncAnthropic(# This is the default and can be omittedapi_key=os.environ.get("ANTHROPIC_API_KEY"),)asyncdefmain()->None:message=awaitclient.messages.create(max_tokens=1024,messages=[{"role":"user","content":"How does a court case get to the supreme court?",}],model="claude-2.1",)print(message.content)asyncio.run(main())Functionality between the synchronous and asynchronous clients is otherwise identical.Streaming ResponsesWe provide support for streaming responses using Server Side Events (SSE).fromanthropicimportAnthropicclient=Anthropic()stream=client.messages.create(max_tokens=1024,messages=[{"role":"user","content":"your prompt here",}],model="claude-2.1",stream=True,)foreventinstream:print(event.type)The async client uses the exact same interface.fromanthropicimportAnthropicclient=Anthropic()stream=awaitclient.messages.create(max_tokens=1024,messages=[{"role":"user","content":"your prompt here",}],model="claude-2.1",stream=True,)asyncforeventinstream:print(event.type)Streaming HelpersThis library provides several conveniences for streaming messages, for example:importasynciofromanthropicimportAsyncAnthropicclient=AsyncAnthropic()asyncdefmain()->None:asyncwithclient.messages.stream(max_tokens=1024,messages=[{"role":"user","content":"Say hello there!",}],model="claude-2.1",)asstream:asyncfortextinstream.text_stream:print(text,end="",flush=True)print()message=awaitstream.get_final_message()print(message.model_dump_json(indent=2))asyncio.run(main())Streaming withclient.messages.stream(...)exposesvarious helpers for your convenienceincluding event handlers and accumulation.Alternatively, you can useclient.messages.create(..., stream=True)which only returns an async iterable of the events in the stream and thus uses less memory (it does not build up a final message object for you).AWS BedrockThis library also provides support for theAnthropic Bedrock APIif you install this library with thebedrockextra, e.g.pip install -U anthropic[bedrock].You can then import and instantiate a separateAnthropicBedrockclass, the rest of the API is the same.fromanthropicimportAI_PROMPT,HUMAN_PROMPT,AnthropicBedrockclient=AnthropicBedrock()completion=client.completions.create(model="anthropic.claude-instant-v1",prompt=f"{HUMAN_PROMPT}hey!{AI_PROMPT}",stop_sequences=[HUMAN_PROMPT],max_tokens_to_sample=500,temperature=0.5,top_k=250,top_p=0.5,)print(completion.completion)For a more fully fledged example seeexamples/bedrock.py.Token countingYou can estimate billing for a given request with theclient.count_tokens()method, eg:client=Anthropic()client.count_tokens('Hello world!')# 3Using typesNested request parameters areTypedDicts. Responses arePydantic models, which provide helper methods for things like:Serializing back into JSON,model.model_dump_json(indent=2, exclude_unset=True)Converting to a dictionary,model.model_dump(exclude_unset=True)Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, setpython.analysis.typeCheckingModetobasic.Handling errorsWhen the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass ofanthropic.APIConnectionErroris raised.When the API returns a non-success status code (that is, 4xx or 5xx
response), a subclass ofanthropic.APIStatusErroris raised, containingstatus_codeandresponseproperties.All errors inherit fromanthropic.APIError.importanthropicfromanthropicimportAnthropicclient=Anthropic()try:client.messages.create(max_tokens=1024,messages=[{"role":"user","content":"your prompt here",}],model="claude-2.1",)exceptanthropic.APIConnectionErrorase:print("The server could not be reached")print(e.__cause__)# an underlying Exception, likely raised within httpx.exceptanthropic.RateLimitErrorase:print("A 429 status code was received; we should back off a bit.")exceptanthropic.APIStatusErrorase:print("Another non-200-range status code was received")print(e.status_code)print(e.response)Error codes are as followed:Status CodeError Type400BadRequestError401AuthenticationError403PermissionDeniedError404NotFoundError422UnprocessableEntityError429RateLimitError>=500InternalServerErrorN/AAPIConnectionErrorRetriesCertain errors are automatically retried 2 times by default, with a short exponential backoff.
Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
429 Rate Limit, and >=500 Internal errors are all retried by default.You can use themax_retriesoption to configure or disable retry settings:fromanthropicimportAnthropic# Configure the default for all requests:client=Anthropic(# default is 2max_retries=0,)# Or, configure per-request:client.with_options(max_retries=5).messages.create(max_tokens=1024,messages=[{"role":"user","content":"Can you help me effectively ask for a raise at work?",}],model="claude-2.1",)TimeoutsBy default requests time out after 10 minutes. You can configure this with atimeoutoption,
which accepts a float or anhttpx.Timeoutobject:fromanthropicimportAnthropic# Configure the default for all requests:client=Anthropic(# 20 seconds (default is 10 minutes)timeout=20.0,)# More granular control:client=Anthropic(timeout=httpx.Timeout(60.0,read=5.0,write=10.0,connect=2.0),)# Override per-request:client.with_options(timeout=5*1000).messages.create(max_tokens=1024,messages=[{"role":"user","content":"Where can I get a good coffee in my neighbourhood?",}],model="claude-2.1",)On timeout, anAPITimeoutErroris thrown.Note that requests that time out areretried twice by default.Default HeadersWe automatically send theanthropic-versionheader set to2023-06-01.If you need to, you can override it by setting default headers per-request or on the client object.Be aware that doing so may result in incorrect types and other unexpected or undefined behavior in the SDK.fromanthropicimportAnthropicclient=Anthropic(default_headers={"anthropic-version":"My-Custom-Value"},)AdvancedLoggingWe use the standard libraryloggingmodule.You can enable logging by setting the environment variableANTHROPIC_LOGtodebug.$exportANTHROPIC_LOG=debugHow to tell whetherNonemeansnullor missingIn an API response, a field may be explicitlynull, or missing entirely; in either case, its value isNonein this library. You can differentiate the two cases with.model_fields_set:ifresponse.my_fieldisNone:if'my_field'notinresponse.model_fields_set:print('Got json like{}, without a "my_field" key present at all.')else:print('Got json like {"my_field": null}.')Accessing raw response data (e.g. headers)The "raw" Response object can be accessed by prefixing.with_raw_response.to any HTTP method call, e.g.,fromanthropicimportAnthropicclient=Anthropic()response=client.messages.with_raw_response.create(max_tokens=1024,messages=[{"role":"user","content":"Where can I get a good coffee in my neighbourhood?",}],model="claude-2.1",)print(response.headers.get('X-My-Header'))message=response.parse()# get the object that `messages.create()` would have returnedprint(message.content)These methods return anLegacyAPIResponseobject. This is a legacy class as we're changing it slightly in the next major version.For the sync client this will mostly be the same with the exception
ofcontent&textwill be methods instead of properties. In the
async client, all methods will be async.A migration script will be provided & the migration in general should
be smooth..with_streaming_responseThe above interface eagerly reads the full response body when you make the request, which may not always be what you want.To stream the response body, use.with_streaming_responseinstead, which requires a context manager and only reads the response body once you call.read(),.text(),.json(),.iter_bytes(),.iter_text(),.iter_lines()or.parse(). In the async client, these are async methods.As such,.with_streaming_responsemethods return a differentAPIResponseobject, and the async client returns anAsyncAPIResponseobject.withclient.messages.with_streaming_response.create(max_tokens=1024,messages=[{"role":"user","content":"Where can I get a good coffee in my neighbourhood?",}],model="claude-2.1",)asresponse:print(response.headers.get("X-My-Header"))forlineinresponse.iter_lines():print(line)The context manager is required so that the response will reliably be closed.Configuring the HTTP clientYou can directly override thehttpx clientto customize it for your use case, including:Support for proxiesCustom transportsAdditionaladvancedfunctionalityimporthttpxfromanthropicimportAnthropicclient=Anthropic(# Or use the `ANTHROPIC_BASE_URL` env varbase_url="http://my.test.server.example.com:8083",http_client=httpx.Client(proxies="http://my.test.proxy.example.com",transport=httpx.HTTPTransport(local_address="0.0.0.0"),),)Managing HTTP resourcesBy default the library closes underlying HTTP connections whenever the client isgarbage collected. You can manually close the client using the.close()method if desired, or with a context manager that closes when exiting.VersioningThis package generally followsSemVerconventions, though certain backwards-incompatible changes may be released as minor versions:Changes that only affect static types, without breaking runtime behavior.Changes to library internals which are technically public but not intended or documented for external use.(Please open a GitHub issue to let us know if you are relying on such internals).Changes that we do not expect to impact the vast majority of users in practice.We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.We are keen for your feedback; please open anissuewith questions, bugs, or suggestions.RequirementsPython 3.7 or higher.