Claude Messages | Documentazione API

# Claude Messages

Native Claude Messages-compatible API. This endpoint uses Anthropic Messages request and response shapes, including tool calls and Anthropic SSE events.

POST https://api.apihop.ai/anthropic/v1/messages

Native Claude Messages-compatible API. This endpoint uses Anthropic Messages request and response shapes, including tool calls and Anthropic SSE events.

Claude Sonnet 4.6 (`claude-sonnet-4-6`) is supported by the upstream supplier but is not currently published on RequestBeam. It is not an active integration default. Before calling any model, confirm access with your own `GET https://api.apihop.ai/v1/models` response.

```text
POST https://api.apihop.ai/anthropic/v1/messages
```

## Authentication

All requests require a RequestBeam API Key. Anthropic SDKs, Claude Code, and compatible clients usually use `x-api-key`; plain HTTP clients may also use Bearer Token authentication.

```http
x-api-key: YOUR_REQUESTBEAM_API_KEY
anthropic-version: 2023-06-01
```

```http
Authorization: Bearer YOUR_REQUESTBEAM_API_KEY
anthropic-version: 2023-06-01
```

## Body

### `model` (string, required, Default: claude-sonnet-5-5)

Supported Claude model IDs.

- `claude-fable-5`
- `claude-fable-5-1`
- `claude-opus-4-6`
- `claude-opus-4-7`
- `claude-opus-4-8`
- `claude-opus-5`
- `claude-opus-5-5`
- `claude-sonnet-5`
- `claude-sonnet-5-5`

Use `GET https://api.apihop.ai/v1/models` for the models currently available to your API Key.

### `max_tokens` (integer, required)

Maximum number of output tokens, as a positive safe integer. This budget includes both thinking and final text output tokens. Missing, zero, negative, fractional, string, or unsafe-integer values return HTTP `400` with `invalid_request_error` before generation or billing. The model may impose a lower maximum.

For models that produce thinking, a small budget such as `128` may yield only thinking blocks before ending with `stop_reason: "max_tokens"`, without text output. Set an explicit budget for the task and the selected model, allowing room for thinking and the final answer. The values in the examples are editable allowances, not upstream defaults or model limits; larger allowances may increase output usage and cost.

### `messages` (object[], required)

Conversation messages. Each message contains `role` and `content`.

`role` supports `user` and `assistant`. `content` may be a string or an array of content blocks.

### `system` (string | object[])

System prompt. Anthropic Messages uses a top-level `system` field instead of a `system` role in `messages`.

### `stream` (boolean, Default: false)

Whether to return Anthropic SSE events.

### `temperature` (number)

Sampling temperature. Accepted values and effects vary by the selected model.

### `top_p` (number)

Nucleus sampling parameter. Acceptance does not guarantee that it changes generation behavior.

### `top_k` (integer)

Top-k sampling parameter. Support depends on the selected model.

### `stop_sequences` (string[])

Stop sequences.

Requests with nonempty stop sequences avoid model services known not to support them; if no compatible service is available, the request returns `400` before generation or billing.

### `tools` (object[])

Anthropic tool definitions. Function tools usually include `name`, `description`, and `input_schema`.

### `tool_choice` (object)

Tool selection policy, such as `{ "type": "auto" }` or `{ "type": "tool", "name": "..." }`.

### `thinking` (object)

Native Anthropic thinking configuration, subject to the selected model and provider's support. Claude 4.5 uses `{ "type": "enabled", "budget_tokens": 1024 }`; Claude Sonnet/Opus 4.6 also support adaptive thinking. Do not apply a manual budget to every model version. In tool continuations, return the complete ordered assistant content, including `thinking`, `signature`, `redacted_thinking` and `tool_use`, unchanged. Keep the thinking configuration and required `anthropic-beta` headers consistent through the tool round trip. For SSE, concatenate `signature_delta.signature` fragments for the same content block; an empty thinking summary does not mean its signature can be discarded. A provider account access rejection is an upstream failure, not evidence of an invalid signature. Recognized Bedrock account access rejections return HTTP 502 with `api_error`; ordinary client validation errors retain HTTP 400. Acceptance still requires an enabled upstream account.

### `metadata` (object)

Request metadata.

### Prompt Caching

Add `cache_control: { "type": "ephemeral" }` to a `system` or message content block. Cache usage may include `cache_creation_input_tokens`, `cache_read_input_tokens`, and supported 5-minute or 1-hour creation buckets. A 1-hour TTL also requires the corresponding `anthropic-beta` header.

## Request Examples

### Non-Streaming

```json
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself in one sentence."
    }
  ],
  "stream": false
}
```

### Streaming

```json
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Reply exactly OK."
    }
  ],
  "stream": true
}
```

## Response

Non-streaming responses keep the Anthropic Message shape.

### `id` (string)

Response ID, such as `msg_...`.

### `type` (string)

Object type, usually `message`.

### `role` (string)

Usually `assistant`.

### `model` (string)

Actual Claude model used.

### `content` (object[])

Native output content blocks, including `text`, `tool_use`, and `thinking` when used.

### `stop_reason` (string)

Stop reason, such as `end_turn`, `max_tokens`, `stop_sequence`, or `tool_use`.

### `usage` (object)

Token usage, including `input_tokens` and `output_tokens`. Cache token fields are included when present.

### Success Example

```json
{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "Hello, I am Claude and can help with writing, coding, and analysis tasks."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "output_tokens": 24
  }
}
```

## Streaming Response

When `stream: true`, the endpoint returns Anthropic SSE events. Common events include:

- `message_start`
- `content_block_start`
- `content_block_delta`
- `content_block_stop`
- `ping`
- `message_delta`
- `message_stop`

## Error Response

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for the full code reference, protocol differences, and diagnostic steps.

Error responses use the Anthropic-style shape:

```json
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid credentials or API key has expired."
  }
}
```

API nativa compatibile con Claude Messages. Questo endpoint usa le strutture di richiesta e risposta Anthropic Messages, comprese chiamate agli strumenti ed eventi SSE Anthropic.

Claude Sonnet 4.6 (claude-sonnet-4-6) è supportato dal fornitore a monte, ma non è attualmente pubblicato su RequestBeam. Non è il modello predefinito di un’integrazione attiva. Prima di chiamare qualsiasi modello, verifica l’accesso con la tua risposta di GET https://api.apihop.ai/v1/models.

text

POST https://api.apihop.ai/anthropic/v1/messages

Autenticazione

Tutte le richieste richiedono una chiave API RequestBeam. Gli SDK Anthropic, Claude Code e i client compatibili usano solitamente x-api-key; i normali client HTTP possono usare anche l’autenticazione con token Bearer.

http

x-api-key: YOUR_REQUESTBEAM_API_KEY
anthropic-version: 2023-06-01

http

Authorization: Bearer YOUR_REQUESTBEAM_API_KEY
anthropic-version: 2023-06-01

Corpo della richiesta

modelstringobbligatorioPredefinito: claude-sonnet-5-5

ID dei modelli Claude supportati.

claude-fable-5
claude-fable-5-1
claude-opus-4-6
claude-opus-4-7
claude-opus-4-8
claude-opus-5
claude-opus-5-5
claude-sonnet-5
claude-sonnet-5-5

Usa GET https://api.apihop.ai/v1/models per vedere i modelli attualmente disponibili per la tua chiave API.

max_tokensintegerobbligatorio

Numero massimo di token di output, espresso come intero positivo sicuro. Questo budget include i token di ragionamento e del testo finale. Valori mancanti, zero, negativi, frazionari, stringhe o interi non sicuri restituiscono HTTP 400 con invalid_request_error prima della generazione o della fatturazione. Il modello può imporre un massimo inferiore.

Per i modelli che producono ragionamento, un budget ridotto come 128 può generare solo blocchi di ragionamento prima di terminare con stop_reason: "max_tokens", senza testo. Imposta un budget esplicito per l’attività e il modello scelto, lasciando spazio al ragionamento e alla risposta finale. I valori degli esempi sono quote modificabili, non valori predefiniti del fornitore né limiti del modello; quote maggiori possono aumentare uso di output e costi.

messagesobject[]obbligatorio

Messaggi della conversazione. Ogni messaggio contiene role e content.

role supporta user e assistant. content può essere una stringa o un array di blocchi di contenuto.

systemstring | object[]

Prompt di sistema. Anthropic Messages usa un campo system di primo livello invece di un ruolo system in messages.

streambooleanPredefinito: false

Indica se restituire eventi SSE Anthropic.

temperaturenumber

Temperatura di campionamento. Valori accettati ed effetti variano secondo il modello scelto.

top_pnumber

Parametro di campionamento nucleus. L’accettazione non garantisce una modifica del comportamento di generazione.

top_kinteger

Parametro di campionamento top-k. Il supporto dipende dal modello scelto.

stop_sequencesstring[]

Sequenze di arresto.

Le richieste con sequenze di arresto non vuote evitano servizi di modello noti per non supportarle; se non è disponibile un servizio compatibile, la richiesta restituisce 400 prima di generazione o fatturazione.

toolsobject[]

Definizioni degli strumenti Anthropic. Gli strumenti funzione includono solitamente name, description e input_schema.

tool_choiceobject

Criterio di scelta degli strumenti, per esempio { "type": "auto" } o { "type": "tool", "name": "..." }.

thinkingobject

Configurazione nativa del ragionamento Anthropic, soggetta al supporto del modello e del fornitore scelti. Claude 4.5 usa { "type": "enabled", "budget_tokens": 1024 }; Claude Sonnet/Opus 4.6 supportano anche il ragionamento adattivo. Non applicare un budget manuale a ogni versione del modello. Nelle continuazioni degli strumenti, restituisci invariato l’intero contenuto ordinato dell’assistente, inclusi thinking, signature, redacted_thinking e tool_use. Mantieni coerenti la configurazione del ragionamento e le intestazioni anthropic-beta richieste durante l’intero ciclo dello strumento. Per SSE, concatena i frammenti signature_delta.signature dello stesso blocco; un riepilogo vuoto del ragionamento non consente di scartarne la firma. Un rifiuto di accesso all’account del fornitore è un errore a monte, non prova di una firma non valida. I rifiuti riconosciuti di accesso all’account Bedrock restituiscono HTTP 502 con api_error; i normali errori di validazione del client restano HTTP 400. L’accettazione richiede comunque un account a monte abilitato.

metadataobject

Metadati della richiesta.

Cache dei prompt

Aggiungi cache_control: { "type": "ephemeral" } a un blocco system o al contenuto di un messaggio. L’utilizzo della cache può includere cache_creation_input_tokens, cache_read_input_tokens e intervalli di creazione supportati di 5 minuti o 1 ora. Un TTL di 1 ora richiede anche la corrispondente intestazione anthropic-beta.

Esempi di richiesta

Senza streaming

json

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself in one sentence."
    }
  ],
  "stream": false
}

Con streaming

json

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Reply exactly OK."
    }
  ],
  "stream": true
}

Risposta

Le risposte senza streaming mantengono la struttura Anthropic Message.

idstring

ID della risposta, per esempio msg_....

typestring

Tipo di oggetto, solitamente message.

rolestring

Solitamente assistant.

modelstring

Modello Claude effettivamente usato.

contentobject[]

Blocchi di contenuto di output nativi, inclusi text, tool_use e thinking quando usato.

stop_reasonstring

Motivo dell’arresto, per esempio end_turn, max_tokens, stop_sequence o tool_use.

usageobject

Utilizzo dei token, inclusi input_tokens e output_tokens. I campi dei token di cache sono inclusi quando presenti.

Esempio di successo

json

{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "Hello, I am Claude and can help with writing, coding, and analysis tasks."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "output_tokens": 24
  }
}

Risposta in streaming

Con stream: true, l’endpoint restituisce eventi SSE Anthropic. Gli eventi comuni includono:

message_start
content_block_start
content_block_delta
content_block_stop
ping
message_delta
message_stop

Risposta di errore

Consulta Codici di errore e risoluzione dei problemi per il riferimento completo, le differenze tra protocolli e i passaggi diagnostici.

Le risposte di errore usano la struttura nello stile Anthropic:

json

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid credentials or API key has expired."
  }
}