Implementation:Anthropics Anthropic sdk python Completions Resource
| Knowledge Sources | |
|---|---|
| Domains | SDK_Infrastructure, API_Resources |
| Last Updated | 2026-02-15 12:00 GMT |
Overview
Legacy Text Completions API resource classes (Completions and AsyncCompletions) providing sync and async create() methods that post to the /v1/complete endpoint.
Description
This module implements the legacy Text Completions API resource. The Completions class (sync) and AsyncCompletions class (async) each extend SyncAPIResource and AsyncAPIResource respectively, providing a create() method with three overloaded signatures: non-streaming (returns Completion), streaming (returns Stream[Completion] or AsyncStream[Completion]), and a generic boolean-typed stream variant.
The Text Completions API is explicitly marked as legacy. Anthropic recommends using the Messages API going forward, as future models and features will not be compatible with Text Completions. The implementation uses the @required_args decorator to enforce runtime parameter validation matching the overloaded signatures. It transforms request parameters via maybe_transform, posts to /v1/complete, and applies a 600-second timeout override when the default client timeout is active.
Each primary class also exposes with_raw_response and with_streaming_response cached properties that return wrapper classes (CompletionsWithRawResponse, CompletionsWithStreamingResponse, and their async counterparts) for accessing raw HTTP response data or lazily streamed response bodies.
Usage
Use this resource when you need to interact with the legacy Text Completions API. For new projects, the Messages API (client.messages.create()) is strongly recommended instead. The completions resource is accessed via client.completions.create().
Code Reference
Source Location
- Repository: Anthropic SDK Python
- File:
src/anthropic/resources/completions.py(845 lines)
Classes
| Class | Parent | Description |
|---|---|---|
Completions |
SyncAPIResource |
Synchronous completions resource |
AsyncCompletions |
AsyncAPIResource |
Asynchronous completions resource |
CompletionsWithRawResponse |
-- | Wrapper returning raw httpx.Response objects
|
AsyncCompletionsWithRawResponse |
-- | Async wrapper returning raw responses |
CompletionsWithStreamingResponse |
-- | Wrapper for lazily streamed response bodies |
AsyncCompletionsWithStreamingResponse |
-- | Async wrapper for lazily streamed response bodies |
Signature
# Sync (non-streaming)
class Completions(SyncAPIResource):
def create(
self,
*,
max_tokens_to_sample: int,
model: ModelParam,
prompt: str,
metadata: MetadataParam | Omit = omit,
stop_sequences: SequenceNotStr[str] | Omit = omit,
stream: Literal[False] | Omit = omit,
temperature: float | Omit = omit,
top_k: int | Omit = omit,
top_p: float | Omit = omit,
betas: List[AnthropicBetaParam] | Omit = omit,
extra_headers: Headers | None = None,
extra_query: Query | None = None,
extra_body: Body | None = None,
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> Completion: ...
# Sync (streaming)
def create(
self,
*,
max_tokens_to_sample: int,
model: ModelParam,
prompt: str,
stream: Literal[True],
...
) -> Stream[Completion]: ...
# Async variant mirrors the same signatures
class AsyncCompletions(AsyncAPIResource):
async def create(...) -> Completion: ...
async def create(..., stream: Literal[True]) -> AsyncStream[Completion]: ...
Import
from anthropic import Anthropic, AsyncAnthropic
# Access via client instance
client = Anthropic()
client.completions.create(...)
I/O Contract
Input Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
max_tokens_to_sample |
int |
Yes | Maximum number of tokens to generate before stopping |
model |
ModelParam |
Yes | Model identifier (e.g., "claude-2.1")
|
prompt |
str |
Yes | The prompt text using \n\nHuman: / \n\nAssistant: turn format
|
metadata |
Omit | No | Request metadata object |
stop_sequences |
Omit | No | Custom stop sequences |
stream |
Omit | No | Enable server-sent events streaming |
temperature |
Omit | No | Randomness (0.0 to 1.0, default 1.0) |
top_k |
Omit | No | Top-K sampling parameter |
top_p |
Omit | No | Nucleus sampling parameter |
betas |
Omit | No | Beta feature flags sent via anthropic-beta header
|
Output
| Condition | Return Type | Description |
|---|---|---|
stream=False or omitted |
Completion |
A single completion response object |
stream=True (sync) |
Stream[Completion] |
Iterable stream of completion events |
stream=True (async) |
AsyncStream[Completion] |
Async iterable stream of completion events |
API Endpoint
| Method | Path | Timeout |
|---|---|---|
| POST | /v1/complete |
600 seconds (overrides default when default timeout is active) |
Usage Examples
import anthropic
client = anthropic.Anthropic()
# Non-streaming completion (legacy API)
completion = client.completions.create(
model="claude-2.1",
max_tokens_to_sample=256,
prompt="\n\nHuman: Tell me a haiku about trees.\n\nAssistant:",
)
print(completion.completion)
# Streaming completion (legacy API)
stream = client.completions.create(
model="claude-2.1",
max_tokens_to_sample=256,
prompt="\n\nHuman: Tell me a story.\n\nAssistant:",
stream=True,
)
for event in stream:
print(event.completion, end="")
# Async usage
import asyncio
async def main():
async_client = anthropic.AsyncAnthropic()
completion = await async_client.completions.create(
model="claude-2.1",
max_tokens_to_sample=256,
prompt="\n\nHuman: Hello!\n\nAssistant:",
)
print(completion.completion)
asyncio.run(main())
# Access raw response headers
raw = client.completions.with_raw_response.create(
model="claude-2.1",
max_tokens_to_sample=256,
prompt="\n\nHuman: Hi\n\nAssistant:",
)
print(raw.headers)
completion = raw.parse()
Implementation Details
Timeout Override
The create() method applies a 600-second timeout when the client is using the default timeout. This accommodates long-running completions:
if not is_given(timeout) and self._client.timeout == DEFAULT_TIMEOUT:
timeout = 600
Beta Header Handling
Beta flags are joined into a comma-separated anthropic-beta header:
extra_headers = {
**strip_not_given({
"anthropic-beta": ",".join(str(e) for e in betas) if is_given(betas) else not_given
}),
**(extra_headers or {}),
}