# Text Completions API (Legacy)

The Text Completions API is a legacy API for generating text completions using Claude models. This API is maintained for backwards compatibility, but the [Messages API](./messages.md) is recommended for new implementations.

**Note:** Future models and features will not be compatible with Text Completions. See the [migration guide](https://docs.anthropic.com/en/api/migrating-from-text-completions-to-messages) for guidance on migrating from Text Completions to Messages.

## Capabilities

### Create Completion

Creates a text completion using the legacy prompt format with `\n\nHuman:` and `\n\nAssistant:` conversational turns.

```typescript { .api }
/**
 * Create a Text Completion (Legacy).
 *
 * @param params - Completion parameters
 * @param options - Optional request options
 * @returns APIPromise resolving to a Completion or Stream<Completion>
 */
client.completions.create(
  params: CompletionCreateParams
): APIPromise<Completion> | APIPromise<Stream<Completion>>;
```

**Usage Example:**

```typescript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// Non-streaming completion
const completion = await client.completions.create({
  max_tokens_to_sample: 256,
  model: 'claude-sonnet-4-5-20250929',
  prompt: '\n\nHuman: Hello, world!\n\nAssistant:',
});

console.log(completion.completion);

// Streaming completion
const stream = await client.completions.create({
  max_tokens_to_sample: 256,
  model: 'claude-sonnet-4-5-20250929',
  prompt: '\n\nHuman: Tell me a story\n\nAssistant:',
  stream: true,
});

for await (const chunk of stream) {
  console.log(chunk.completion);
}
```

## Types

### Completion

The response object returned by the Text Completions API.

```typescript { .api }
interface Completion {
  /**
   * Unique object identifier.
   * The format and length of IDs may change over time.
   */
  id: string;

  /**
   * The resulting completion up to and excluding the stop sequences.
   */
  completion: string;

  /**
   * The model that completed your prompt.
   * See https://docs.anthropic.com/en/docs/models-overview for details.
   */
  model: Model;

  /**
   * The reason that generation stopped.
   *
   * Possible values:
   * - "stop_sequence": reached a stop sequence (provided or built-in)
   * - "max_tokens": exceeded max_tokens_to_sample or model's maximum
   */
  stop_reason: string | null;

  /**
   * Object type. For Text Completions, this is always "completion".
   */
  type: 'completion';
}
```

### CompletionCreateParams

Parameters for creating a text completion.

```typescript { .api }
type CompletionCreateParams =
  | CompletionCreateParamsNonStreaming
  | CompletionCreateParamsStreaming;

interface CompletionCreateParamsBase {
  /**
   * The maximum number of tokens to generate before stopping.
   *
   * Note that models may stop before reaching this maximum.
   * This parameter only specifies the absolute maximum number of tokens to generate.
   */
  max_tokens_to_sample: number;

  /**
   * The model that will complete your prompt.
   * See https://docs.anthropic.com/en/docs/models-overview for details.
   */
  model: Model;

  /**
   * The prompt that you want Claude to complete.
   *
   * For proper response generation, format your prompt using alternating
   * `\n\nHuman:` and `\n\nAssistant:` conversational turns.
   *
   * Example: "\n\nHuman: {userQuestion}\n\nAssistant:"
   *
   * See https://docs.claude.com/en/api/prompt-validation and
   * https://docs.claude.com/en/docs/intro-to-prompting for more details.
   */
  prompt: string;

  /**
   * An object describing metadata about the request.
   */
  metadata?: Metadata;

  /**
   * Sequences that will cause the model to stop generating.
   *
   * Models stop on "\n\nHuman:" and may include additional built-in stop
   * sequences in the future. By providing stop_sequences, you may include
   * additional strings that will cause the model to stop generating.
   */
  stop_sequences?: string[];

  /**
   * Whether to incrementally stream the response using server-sent events.
   * See https://docs.claude.com/en/api/streaming for details.
   */
  stream?: boolean;

  /**
   * Amount of randomness injected into the response.
   *
   * Defaults to 1.0. Ranges from 0.0 to 1.0.
   * Use temperature closer to 0.0 for analytical/multiple choice tasks,
   * and closer to 1.0 for creative and generative tasks.
   *
   * Note that even with temperature of 0.0, results will not be fully deterministic.
   */
  temperature?: number;

  /**
   * Only sample from the top K options for each subsequent token.
   *
   * Used to remove "long tail" low probability responses.
   * See 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;

  /**
   * Use nucleus sampling.
   *
   * In nucleus sampling, we compute the cumulative distribution over all options
   * 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;

  /**
   * Optional header to specify the beta version(s) you want to use.
   */
  betas?: AnthropicBeta[];
}

interface CompletionCreateParamsNonStreaming extends CompletionCreateParamsBase {
  /**
   * Whether to incrementally stream the response using server-sent events.
   */
  stream?: false;
}

interface CompletionCreateParamsStreaming extends CompletionCreateParamsBase {
  /**
   * Whether to incrementally stream the response using server-sent events.
   */
  stream: true;
}
```