@anthropic-ai/sdk 0.14.1 → 0.16.0

package/src/resources/messages.ts

@@ -12,11 +12,11 @@ export class Messages extends APIResource {
   /**
    * Create a Message.
    *
-   * Send a structured list of input messages, and the model will generate the next
-   * message in the conversation.
+   * Send a structured list of input messages with text and/or image content, and the
+   * model will generate the next message in the conversation.
    *
-   * Messages can be used for either single queries to the model or for multi-turn
-   * conversations.
+   * The Messages API can be used for for either single queries or stateless
+   * multi-turn conversations.
    */
   create(body: MessageCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<Message>;
   create(
@@ -75,6 +75,22 @@ export interface ContentBlockStopEvent {
   type: 'content_block_stop';
 }
 
+export interface ImageBlockParam {
+  source: ImageBlockParam.Source;
+
+  type?: 'image';
+}
+
+export namespace ImageBlockParam {
+  export interface Source {
+    data: string;
+
+    media_type: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+
+    type?: 'base64';
+  }
+}
+
 export interface Message {
   /**
    * Unique object identifier.
@@ -87,7 +103,7 @@ export interface Message {
    * Content generated by the model.
    *
    * This is an array of content blocks, each of which has a `type` that determines
-   * its shape. Currently, the only `type` available is `"text"`.
+   * its shape. Currently, the only `type` in responses is `"text"`.
    *
    * Example:
    *
@@ -107,10 +123,7 @@ export interface Message {
    *     "role": "user",
    *     "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"
    *   },
-   *   {
-   *     "role": "assistant",
-   *     "content": "The best answer is ("
-   *   }
+   *   { "role": "assistant", "content": "The best answer is (" }
    * ]
    * ```
    *
@@ -152,16 +165,33 @@ export interface Message {
   stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | null;
 
   /**
-   * Which custom stop sequence was generated.
+   * Which custom stop sequence was generated, if any.
    *
-   * This value will be non-null if one of your custom stop sequences was generated.
+   * This value will be a non-null string if one of your custom stop sequences was
+   * generated.
    */
   stop_sequence: string | null;
 
+  /**
+   * Object type.
+   *
+   * For Messages, this is always `"message"`.
+   */
   type: 'message';
 
   /**
-   * Container for the number of tokens used.
+   * Billing and rate-limit usage.
+   *
+   * Anthropic's API bills and rate-limits by token counts, as tokens represent the
+   * underlying cost to our systems.
+   *
+   * Under the hood, the API transforms requests into a format suitable for the
+   * model. The model's output then goes through a parsing stage before becoming an
+   * API response. As a result, the token counts in `usage` will not match one-to-one
+   * with the exact visible content of an API request or response.
+   *
+   * For example, `output_tokens` will be non-zero, even for an empty string response
+   * from Claude.
    */
   usage: Usage;
 }
@@ -172,7 +202,18 @@ export interface MessageDeltaEvent {
   type: 'message_delta';
 
   /**
-   * Container for the number of tokens used.
+   * Billing and rate-limit usage.
+   *
+   * Anthropic's API bills and rate-limits by token counts, as tokens represent the
+   * underlying cost to our systems.
+   *
+   * Under the hood, the API transforms requests into a format suitable for the
+   * model. The model's output then goes through a parsing stage before becoming an
+   * API response. As a result, the token counts in `usage` will not match one-to-one
+   * with the exact visible content of an API request or response.
+   *
+   * For example, `output_tokens` will be non-zero, even for an empty string response
+   * from Claude.
    */
   usage: MessageDeltaUsage;
 }
@@ -193,7 +234,7 @@ export interface MessageDeltaUsage {
 }
 
 export interface MessageParam {
-  content: string | Array<TextBlock>;
+  content: string | Array<TextBlock | ImageBlockParam>;
 
   role: 'user' | 'assistant';
 }
@@ -250,8 +291,7 @@ export interface MessageCreateParamsBase {
    * only specifies the absolute maximum number of tokens to generate.
    *
    * Different models have different maximum values for this parameter. See
-   * [input and output sizes](https://docs.anthropic.com/claude/reference/input-and-output-sizes)
-   * for details.
+   * [models](https://docs.anthropic.com/claude/docs/models-overview) for details.
    */
   max_tokens: number;
 
@@ -291,15 +331,18 @@ export interface MessageCreateParamsBase {
    *
    * ```json
    * [
-   *   { "role": "user", "content": "Please describe yourself using only JSON" },
-   *   { "role": "assistant", "content": "Here is my JSON description:\n{" }
+   *   {
+   *     "role": "user",
+   *     "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"
+   *   },
+   *   { "role": "assistant", "content": "The best answer is (" }
    * ]
    * ```
    *
    * Each input message `content` may be either a single `string` or an array of
-   * content blocks, where each block has a specific `type`. Using a `string` is
-   * shorthand for an array of one content block of type `"text"`. The following
-   * input messages are equivalent:
+   * content blocks, where each block has a specific `type`. Using a `string` for
+   * `content` is shorthand for an array of one content block of type `"text"`. The
+   * following input messages are equivalent:
    *
    * ```json
    * { "role": "user", "content": "Hello, Claude" }
@@ -309,27 +352,42 @@ export interface MessageCreateParamsBase {
    * { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] }
    * ```
    *
-   * See our
-   * [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
-   * for more details on how to best construct prompts.
+   * Starting with Claude 3 models, you can also send image content blocks:
+   *
+   * ```json
+   * {
+   *   "role": "user",
+   *   "content": [
+   *     {
+   *       "type": "image",
+   *       "source": {
+   *         "type": "base64",
+   *         "media_type": "image/jpeg",
+   *         "data": "/9j/4AAQSkZJRg..."
+   *       }
+   *     },
+   *     { "type": "text", "text": "What is in this image?" }
+   *   ]
+   * }
+   * ```
+   *
+   * We currently support the `base64` source type for images, and the `image/jpeg`,
+   * `image/png`, `image/gif`, and `image/webp` media types.
+   *
+   * See [examples](https://docs.anthropic.com/claude/reference/messages-examples)
+   * for more input examples.
    *
    * Note that if you want to include a
-   * [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
-   * you can use the top-level `system` parameter — there is no `"system"` role for
-   * input messages in the Messages API.
+   * [system prompt](https://docs.anthropic.com/claude/docs/system-prompts), you can
+   * use the top-level `system` parameter — there is no `"system"` role for input
+   * messages in the Messages API.
    */
   messages: Array<MessageParam>;
 
   /**
    * The model that will complete your prompt.
    *
-   * As we improve Claude, we develop new versions of it that you can query. The
-   * `model` parameter controls which version of Claude responds to your request.
-   * Right now we offer two model families: Claude, and Claude Instant. You can use
-   * them by setting `model` to `"claude-2.1"` or `"claude-instant-1.2"`,
-   * respectively.
-   *
-   * See [models](https://docs.anthropic.com/claude/reference/selecting-a-model) for
+   * See [models](https://docs.anthropic.com/claude/docs/models-overview) for
    * additional details and options.
    */
   model: string;
@@ -365,15 +423,19 @@ export interface MessageCreateParamsBase {
    *
    * A system prompt is a way of providing context and instructions to Claude, such
    * as specifying a particular goal or role. See our
-   * [guide to system prompts](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts).
+   * [guide to system prompts](https://docs.anthropic.com/claude/docs/system-prompts).
    */
   system?: string;
 
   /**
    * Amount of randomness injected into the response.
    *
-   * Defaults to 1. Ranges from 0 to 1. Use temp closer to 0 for analytical /
-   * multiple choice, and closer to 1 for creative and generative tasks.
+   * Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0`
+   * for analytical / multiple choice, and closer to `1.0` for creative and
+   * generative tasks.
+   *
+   * Note that even with `temperature` of `0.0`, the results will not be fully
+   * deterministic.
    */
   temperature?: number;
 
@@ -382,6 +444,9 @@ export interface MessageCreateParamsBase {
    *
    * Used to remove "long tail" low probability responses.
    * [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).
+   *
+   * Recommended for advanced use cases only. You usually only need to use
+   * `temperature`.
    */
   top_k?: number;
 
@@ -392,6 +457,9 @@ export interface MessageCreateParamsBase {
    * for each subsequent token in decreasing probability order and cut it off once it
    * reaches a particular probability specified by `top_p`. You should either alter
    * `temperature` or `top_p`, but not both.
+   *
+   * Recommended for advanced use cases only. You usually only need to use
+   * `temperature`.
    */
   top_p?: number;
 }
@@ -443,8 +511,7 @@ export interface MessageStreamParams {
    * only specifies the absolute maximum number of tokens to generate.
    *
    * Different models have different maximum values for this parameter. See
-   * [input and output sizes](https://docs.anthropic.com/claude/reference/input-and-output-sizes)
-   * for details.
+   * [models](https://docs.anthropic.com/claude/docs/models-overview) for details.
    */
   max_tokens: number;
 
@@ -484,15 +551,18 @@ export interface MessageStreamParams {
    *
    * ```json
    * [
-   *   { "role": "user", "content": "Please describe yourself using only JSON" },
-   *   { "role": "assistant", "content": "Here is my JSON description:\n{" }
+   *   {
+   *     "role": "user",
+   *     "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"
+   *   },
+   *   { "role": "assistant", "content": "The best answer is (" }
    * ]
    * ```
    *
    * Each input message `content` may be either a single `string` or an array of
-   * content blocks, where each block has a specific `type`. Using a `string` is
-   * shorthand for an array of one content block of type `"text"`. The following
-   * input messages are equivalent:
+   * content blocks, where each block has a specific `type`. Using a `string` for
+   * `content` is shorthand for an array of one content block of type `"text"`. The
+   * following input messages are equivalent:
    *
    * ```json
    * { "role": "user", "content": "Hello, Claude" }
@@ -502,27 +572,42 @@ export interface MessageStreamParams {
    * { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] }
    * ```
    *
-   * See our
-   * [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
-   * for more details on how to best construct prompts.
+   * Starting with Claude 3 models, you can also send image content blocks:
+   *
+   * ```json
+   * {
+   *   "role": "user",
+   *   "content": [
+   *     {
+   *       "type": "image",
+   *       "source": {
+   *         "type": "base64",
+   *         "media_type": "image/jpeg",
+   *         "data": "/9j/4AAQSkZJRg..."
+   *       }
+   *     },
+   *     { "type": "text", "text": "What is in this image?" }
+   *   ]
+   * }
+   * ```
+   *
+   * We currently support the `base64` source type for images, and the `image/jpeg`,
+   * `image/png`, `image/gif`, and `image/webp` media types.
+   *
+   * See [examples](https://docs.anthropic.com/claude/reference/messages-examples)
+   * for more input examples.
    *
    * Note that if you want to include a
-   * [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
-   * you can use the top-level `system` parameter — there is no `"system"` role for
-   * input messages in the Messages API.
+   * [system prompt](https://docs.anthropic.com/claude/docs/system-prompts), you can
+   * use the top-level `system` parameter — there is no `"system"` role for input
+   * messages in the Messages API.
    */
   messages: Array<MessageParam>;
 
   /**
    * The model that will complete your prompt.
    *
-   * As we improve Claude, we develop new versions of it that you can query. The
-   * `model` parameter controls which version of Claude responds to your request.
-   * Right now we offer two model families: Claude, and Claude Instant. You can use
-   * them by setting `model` to `"claude-2.1"` or `"claude-instant-1.2"`,
-   * respectively.
-   *
-   * See [models](https://docs.anthropic.com/claude/reference/selecting-a-model) for
+   * See [models](https://docs.anthropic.com/claude/docs/models-overview) for
    * additional details and options.
    */
   model: string;
@@ -550,15 +635,19 @@ export interface MessageStreamParams {
    *
    * A system prompt is a way of providing context and instructions to Claude, such
    * as specifying a particular goal or role. See our
-   * [guide to system prompts](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts).
+   * [guide to system prompts](https://docs.anthropic.com/claude/docs/system-prompts).
    */
   system?: string;
 
   /**
    * Amount of randomness injected into the response.
    *
-   * Defaults to 1. Ranges from 0 to 1. Use temp closer to 0 for analytical /
-   * multiple choice, and closer to 1 for creative and generative tasks.
+   * Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0`
+   * for analytical / multiple choice, and closer to `1.0` for creative and
+   * generative tasks.
+   *
+   * Note that even with `temperature` of `0.0`, the results will not be fully
+   * deterministic.
    */
   temperature?: number;
 
@@ -567,6 +656,9 @@ export interface MessageStreamParams {
    *
    * Used to remove "long tail" low probability responses.
    * [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).
+   *
+   * Recommended for advanced use cases only. You usually only need to use
+   * `temperature`.
    */
   top_k?: number;
 
@@ -577,6 +669,9 @@ export interface MessageStreamParams {
    * for each subsequent token in decreasing probability order and cut it off once it
    * reaches a particular probability specified by `top_p`. You should either alter
    * `temperature` or `top_p`, but not both.
+   *
+   * Recommended for advanced use cases only. You usually only need to use
+   * `temperature`.
    */
   top_p?: number;
 }
@@ -602,6 +697,7 @@ export namespace Messages {
   export import ContentBlockDeltaEvent = MessagesAPI.ContentBlockDeltaEvent;
   export import ContentBlockStartEvent = MessagesAPI.ContentBlockStartEvent;
   export import ContentBlockStopEvent = MessagesAPI.ContentBlockStopEvent;
+  export import ImageBlockParam = MessagesAPI.ImageBlockParam;
   export import Message = MessagesAPI.Message;
   export import MessageDeltaEvent = MessagesAPI.MessageDeltaEvent;
   export import MessageDeltaUsage = MessagesAPI.MessageDeltaUsage;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.14.1'; // x-release-please-version
+export const VERSION = '0.16.0'; // x-release-please-version

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.14.1";
+export declare const VERSION = "0.16.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.14.1'; // x-release-please-version
+exports.VERSION = '0.16.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.14.1'; // x-release-please-version
+export const VERSION = '0.16.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map