Skip to content

Commit 6fb9c85

Browse files
ericc-chericc-ch
committed
feat: Update Anthropic API documentation and types
1 parent 95a4178 commit 6fb9c85

3 files changed

Lines changed: 70 additions & 226 deletions

File tree

‎docs/anthropic.md‎

Lines changed: 58 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -18,73 +18,84 @@ Creates a model response for the given conversation.
1818

1919
The request body is a JSON object.
2020

21-
| Parameter | Type | Required | Description |
22-
| :--------------- | :-------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
23-
| `model` | string | Yes | The model that will complete your prompt. Example: `claude-3-7-sonnet-20250219`. |
24-
| `messages` | array | Yes | A list of input messages comprising the conversation so far. See [The Message Object](https://www.google.com/search?q=%23the-message-object) below. |
25-
| `max_tokens` | integer | Yes | The maximum number of tokens to generate. Different models have different maximums. |
26-
| `system` | string or array | No | A system prompt to provide context and instructions to Claude, such as specifying a role or goal. |
27-
| `metadata` | object | No | An object for metadata, such as a `user_id`, to help detect abuse. Do not include any personally identifying information. |
28-
| `stop_sequences` | array | No | Custom text sequences that will cause the model to stop generating. |
29-
| `stream` | boolean | No | If set, the response will be incrementally streamed using server-sent events. Defaults to `false`. |
30-
| `temperature` | number | No | The amount of randomness injected into the response, ranging from `0.0` to `1.0`. Defaults to `1.0`. |
31-
| `top_p` | number | No | Use nucleus sampling. The model considers tokens with `top_p` probability mass. Should alter `temperature` or `top_p`, but not both. |
32-
| `top_k` | integer | No | Only sample from the top K options for each subsequent token. Recommended for advanced use cases. |
33-
| `tools` | array | No | A list of tools the model may use. See [The Tool Object](https://www.google.com/search?q=%23the-tool-object) below. |
34-
| `tool_choice` | object | No | Controls how the model should use the provided tools. Can be `auto`, `any`, `tool`, or `none`. |
21+
| Parameter | Type | Required | Description |
22+
| :--------------- | :-------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
23+
| `model` | string | Yes | The model that will complete your prompt. Example: `claude-3-7-sonnet-20250219`. |
24+
| `messages` | array | Yes | A list of input messages comprising the conversation so far. See [The Message Object](https://www.google.com/search?q=%23the-message-object) below. |
25+
| `max_tokens` | integer | Yes | The maximum number of tokens to generate. Different models have different maximum values for this parameter. |
26+
| `system` | string or array | No | A system prompt to provide context and instructions to Claude, such as specifying a role or goal. |
27+
| `metadata` | object | No | An object for metadata, such as a `user_id`, to help detect abuse. Do not include any personally identifying information. |
28+
| `stop_sequences` | array | No | Custom text sequences that will cause the model to stop generating. |
29+
| `stream` | boolean | No | If set, the response will be incrementally streamed using server-sent events. Defaults to `false`. |
30+
| `temperature` | number | No | The amount of randomness injected into the response, ranging from `0.0` to `1.0`. Defaults to `1.0`. |
31+
| `thinking` | object | No | Configuration for enabling Claude's extended thinking process, which shows reasoning steps before the final answer. |
32+
| `top_p` | number | No | Use nucleus sampling. The model considers tokens with `top_p` probability mass. You should alter `temperature` or `top_p`, but not both. |
33+
| `top_k` | integer | No | Only sample from the top K options for each subsequent token. Recommended for advanced use cases only. |
34+
| `tools` | array | No | A list of tools the model may use. See [The Tool Object](https://www.google.com/search?q=%23the-tool-object) below. |
35+
| `tool_choice` | object | No | Controls how the model should use tools. Can be `{"type": "auto"}`, `{"type": "any"}`, `{"type": "tool", "name": "tool_name"}` or `{"type": "none"}`. |
36+
| `service_tier` | string | No | Can be set to `auto` or `standard_only` to determine whether to use priority capacity. |
3537

3638
#### The Message Object
3739

38-
The `messages` array consists of message objects, where each object has a `role` and `content`. Models are trained on alternating `user` and `assistant` turns.
40+
The `messages` array consists of message objects, where each object has a `role` and `content`. Models are trained on alternating `user` and `assistant` conversational turns.
3941

40-
| Parameter | Type | Required | Description |
41-
| :-------- | :-------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |
42-
| `role` | string | Yes | The role of the message author. Must be either `user` or `assistant`. |
43-
| `content` | string or array | Yes | The content of the message. This can be a simple string or an array of content blocks for multimodal input (e.g., text and images). |
42+
| Parameter | Type | Required | Description |
43+
| :-------- | :-------------- | :------- | :---------------------------------------------------------------------------------------------------------- |
44+
| `role` | string | Yes | The role of the message author. Must be either `user` or `assistant`. |
45+
| `content` | string or array | Yes | The content of the message. This can be a simple string or an array of content blocks for multimodal input. |
4446

4547
**Content Blocks:** For multimodal input, the `content` array can contain different types of blocks.
4648

4749
- **`text`**: A block with a `type` of "text" and a `text` field containing the string.
48-
- **`image`**: A block with a `type` of "image" and a `source` object. The source must specify its `type` (e.g., "base64"), `media_type` (e.g., "image/jpeg"), and `data`.
49-
- **`tool_result`**: A block used to return the output of a tool back to the model. It includes the `tool_use_id`, `content`, and an optional `is_error` flag.
50+
- **`image`**: Starting with Claude 3 models, you can send image content blocks. The `source` object must specify a `type` of "base64", a `media_type` (`image/jpeg`, `image/png`, `image/gif`, or `image/webp`), and the `data`.
51+
- **`tool_result`**: A block used to return the output of a tool back to the model. It includes the `tool_use_id`, the `content` from the tool's execution, and an optional `is_error` flag.
5052

5153
#### The Tool Object
5254

5355
The `tools` array allows you to define client-side tools the model can call.
5456

55-
| Parameter | Type | Required | Description |
56-
| :------------- | :----- | :------- | :-------------------------------------------------------------------------------------------------------- |
57-
| `name` | string | Yes | The name of the tool, matching `^[a-zA-Z0-9_-]{1,64}$`. |
58-
| `description` | string | No | A detailed description of what the tool does, which helps the model decide when to use it. |
59-
| `input_schema` | object | Yes | A [JSON Schema](https://json-schema.org/draft/2020-12) object describing the parameters the tool accepts. |
57+
| Parameter | Type | Required | Description |
58+
| :------------- | :----- | :------- | :--------------------------------------------------------------------------------------------------------------- |
59+
| `name` | string | Yes | The name of the tool, which must match the pattern `^[a-zA-Z0-9_-]{1,64}$`. |
60+
| `description` | string | No | A detailed, strongly-recommended description of what the tool does, which helps the model decide when to use it. |
61+
| `input_schema` | object | Yes | A [JSON Schema](https://json-schema.org/draft/2020-12) object describing the parameters the tool accepts. |
6062

6163
#### Response (200 OK)
6264

63-
A successful non-streaming request returns a `Message` object.
65+
A successful **non-streaming** request returns a `Message` object.
6466

65-
| Parameter | Type | Description |
66-
| :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------ |
67-
| `id` | string | A unique identifier for the message object. |
68-
| `type` | string | The object type, which is always `message`. |
69-
| `role` | string | The role of the author, which is always `assistant`. |
70-
| `content` | array | An array of content blocks generated by the model (e.g., `text` or `tool_use`). |
71-
| `model` | string | The model that handled the request. |
72-
| `stop_reason` | string | The reason the model stopped generating tokens. Can be `end_turn`, `max_tokens`, `stop_sequence`, or `tool_use`. |
73-
| `stop_sequence` | string | If the model was stopped by a stop sequence, this field will contain which sequence was generated. Can be null. |
74-
| `usage` | object | An object containing token usage statistics. See [The Usage Object](https://www.google.com/search?q=%23the-usage-object). |
67+
| Parameter | Type | Description |
68+
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------- |
69+
| `id` | string | A unique identifier for the message object. |
70+
| `type` | string | The object type, which is always `message`. |
71+
| `role` | string | The role of the author, which is always `assistant`. |
72+
| `content` | array | An array of content blocks generated by the model (e.g., `text` or `tool_use`). |
73+
| `model` | string | The model that handled the request. |
74+
| `stop_reason` | string | The reason the model stopped generating tokens. Can be `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn`, or `refusal`. |
75+
| `stop_sequence` | string | If the model was stopped by a custom stop sequence, this field will contain which sequence was generated. Can be null. |
76+
| `usage` | object | An object containing token usage statistics. See [The Usage Object](https://www.google.com/search?q=%23the-usage-object). |
77+
78+
#### Streaming Response (200 OK)
79+
80+
If `stream: true` is set, the API streams back a sequence of server-sent events. The response is a series of JSON events that incrementally build the complete message object.
81+
82+
According to the documentation, the `stop_reason` provides insight into the stream's state: in the initial `message_start` event, the `stop_reason` field will be `null`. In all other events, it will be non-null once the stopping condition is known.
7583

7684
#### The Usage Object
7785

7886
The `usage` object details billing and rate-limit token counts.
7987

80-
| Parameter | Type | Description |
81-
| :-------------- | :------ | :------------------------------------- |
82-
| `input_tokens` | integer | The number of input tokens used. |
83-
| `output_tokens` | integer | The number of output tokens generated. |
88+
| Parameter | Type | Description |
89+
| :---------------------------- | :------ | :-------------------------------------------------------------------------- |
90+
| `input_tokens` | integer | The number of input tokens used. |
91+
| `output_tokens` | integer | The number of output tokens generated. |
92+
| `cache_creation_input_tokens` | integer | The number of input tokens used to create a cache entry. |
93+
| `cache_read_input_tokens` | integer | The number of input tokens read from the cache. |
94+
| `service_tier` | string | The service tier used for the request (`standard`, `priority`, or `batch`). |
8495

8596
### Count Message Tokens
8697

87-
Calculates the number of tokens for a given set of messages without executing the model.
98+
Calculates the number of tokens for a given set of messages without creating it.
8899

89100
**Endpoint:** `POST /v1/messages/count_tokens`
90101

@@ -103,9 +114,9 @@ The request accepts a subset of the "Create a Message" parameters.
103114

104115
A successful request returns a JSON object.
105116

106-
| Parameter | Type | Description |
107-
| :------------- | :------ | :------------------------------------------------------------------------------ |
108-
| `input_tokens` | integer | The total number of tokens counted from the messages, system prompt, and tools. |
117+
| Parameter | Type | Description |
118+
| :------------- | :------ | :----------------------------------------------------------------------------------------- |
119+
| `input_tokens` | integer | The total number of tokens across the provided list of messages, system prompt, and tools. |
109120

110121
---
111122

@@ -115,7 +126,7 @@ The Models API allows you to list and retrieve information about available model
115126

116127
### List Models
117128

118-
Lists the currently available models, with the most recent models appearing first.
129+
Lists the currently available models, with the most recently released models appearing first.
119130

120131
**Endpoint:** `GET /v1/models`
121132

@@ -126,7 +137,7 @@ A successful request returns a list of model objects.
126137
| Parameter | Type | Description |
127138
| :--------- | :------ | :------------------------------------------------------------------------------ |
128139
| `data` | array | A list of [Model Objects](https://www.google.com/search?q=%23the-model-object). |
129-
| `has_more` | boolean | Indicates if more results are available for pagination. |
140+
| `has_more` | boolean | Indicates if there are more results in the requested page direction. |
130141

131142
### Get a Model
132143

‎src/routes/messages/anthropic-types.ts‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,13 @@ export interface AnthropicResponse {
6363
role: "assistant"
6464
content: Array<AnthropicResponseContentBlock>
6565
model: string
66-
stop_reason: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | null
66+
stop_reason:
67+
| "end_turn"
68+
| "max_tokens"
69+
| "stop_sequence"
70+
| "tool_use"
71+
| "pause_turn"
72+
| "refusal"
6773
stop_sequence: string | null
6874
usage: {
6975
input_tokens: number
@@ -85,11 +91,10 @@ export interface AnthropicToolUseBlock {
8591
// Anthropic Stream Event Types
8692
export interface AnthropicMessageStartEvent {
8793
type: "message_start"
88-
message: Omit<
89-
AnthropicResponse,
90-
"stop_reason" | "stop_sequence" | "content"
91-
> & {
94+
message: Omit<AnthropicResponse, "content" | "stop_reason" | "stop_sequence"> & {
9295
content: []
96+
stop_reason: null
97+
stop_sequence: null
9398
}
9499
}
95100

@@ -119,8 +124,8 @@ export interface AnthropicContentBlockStopEvent {
119124
export interface AnthropicMessageDeltaEvent {
120125
type: "message_delta"
121126
delta: {
122-
stop_reason: AnthropicResponse["stop_reason"]
123-
stop_sequence: string | null
127+
stop_reason?: AnthropicResponse["stop_reason"]
128+
stop_sequence?: string | null
124129
}
125130
// OpenAI does not provide token usage per chunk, so this is omitted.
126131
// usage: { output_tokens: number }

0 commit comments

Comments
 (0)