Creare un messaggio

POST

messages

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.cometapi.com",
    api_key=os.environ["COMETAPI_KEY"],
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "Hello, world"}
    ],
)

print(message.content[0].text)

{
  "id": "<string>",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "text": "<string>",
      "thinking": "<string>",
      "signature": "<string>",
      "id": "<string>",
      "name": "<string>",
      "input": {}
    }
  ],
  "model": "<string>",
  "stop_sequence": "<string>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "cache_creation_input_tokens": 123,
    "cache_read_input_tokens": 123,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 123,
      "ephemeral_1h_input_tokens": 123
    },
    "output_tokens_details": {
      "thinking_tokens": 123
    }
  }
}

CometAPI supporta nativamente l’API Anthropic Messages, offrendoti accesso diretto ai modelli Claude con funzionalità specifiche di Anthropic. Usa questo endpoint per capacità di Claude come adaptive thinking, prompt caching e controllo dell’effort.

Usa il riferimento ufficiale dell’API Anthropic Messages come fonte autorevole per l’elenco completo dei parametri, lo schema della risposta e il comportamento specifico di Claude. Questa pagina di CometAPI spiega come inviare quel formato di richiesta tramite CometAPI.

I parametri della richiesta Anthropic e i campi della risposta possono cambiare con l’evolversi delle funzionalità di Claude. Controlla la documentazione dell’API Anthropic Messages per l’elenco completo più aggiornato dei parametri e il comportamento specifico del provider.

Molti modelli Claude più recenti rifiutano valori non predefiniti di temperature, top_p e top_k nell’API Messages. Ometti questi campi di campionamento a meno che tu non abbia verificato il supporto per il modello selezionato. Se un modello restituisce un errore di parametro non supportato o deprecato, rimuovi il campo dalla richiesta.

Sia gli header x-api-key sia Authorization: Bearer sono supportati per l’autenticazione. Gli SDK ufficiali di Anthropic usano x-api-key per impostazione predefinita.

Guida rapida

Per usare l’SDK ufficiale di Anthropic con CometAPI, imposta la base URL:

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.cometapi.com",
    api_key=os.environ["COMETAPI_KEY"],
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
    apiKey: process.env.COMETAPI_KEY,
    baseURL: "https://api.cometapi.com",
});

const message = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello!" }],
});
console.log(message.content[0].text);

Controllare l’adaptive thinking

Usa adaptive thinking con output_config.effort per controllare quanto lavoro Claude applica a una risposta. I modelli Claude più recenti rifiutano il formato legacy del thinking manuale thinking={"type": "enabled", "budget_tokens": ...}.

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between a monolithic architecture and microservices for a small engineering team.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

I token di thinking vengono conteggiati nel limite di max_tokens. Imposta max_tokens abbastanza alto sia per il thinking sia per la risposta finale quando usi livelli di effort più elevati.

Memorizzare nella cache i prompt

Per ridurre la latenza e il costo nelle richieste successive, memorizza nella cache prompt di sistema di grandi dimensioni o prefissi di conversazione. Aggiungi cache_control ai blocchi di contenuto che devono essere memorizzati nella cache:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an expert code reviewer. [Long detailed instructions...]",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Review this code..."}],
)

L’utilizzo della cache viene riportato nel campo usage della risposta:

cache_creation_input_tokens — token scritti nella cache (fatturati a una tariffa più alta)
cache_read_input_tokens — token letti dalla cache (fatturati a una tariffa ridotta)

La memorizzazione nella cache dei prompt richiede un minimo di 1,024 tokens nel blocco di contenuto memorizzato nella cache. I contenuti più brevi non verranno memorizzati nella cache.

Trasmettere le risposte in Streaming

Per trasmettere le risposte in Streaming usando Server-Sent Events (SSE), imposta stream: true. Gli eventi arrivano in questo ordine:

message_start — contiene i metadati del messaggio e l’utilizzo iniziale
content_block_start — indica l’inizio di ogni blocco di contenuto
content_block_delta — frammenti di testo incrementali (text_delta)
content_block_stop — indica la fine di ogni blocco di contenuto
message_delta — stop_reason finale e usage completo
message_stop — segnala la fine dello stream

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="")

Controllare l’effort

Per controllare quanto impegno Claude mette nella generazione di una risposta, usa output_config.effort:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Summarize this briefly."}
    ],
    output_config={"effort": "low"},  # "low", "medium", "high", "xhigh", or "max"
)

Usare gli strumenti server

Claude supporta strumenti lato server che vengono eseguiti sull’infrastruttura di Anthropic:

Web Fetch
Web Search

Recupera e analizza contenuti dagli URL:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Analyze the content at https://arxiv.org/abs/1512.03385"}
    ],
    tools=[
        {"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}
    ],
)

Cerca sul web informazioni in tempo reale:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What are the latest developments in AI?"}
    ],
    tools=[
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 5}
    ],
)

Esempio di risposta

Una risposta tipica dall’endpoint Anthropic di CometAPI:

{
  "id": "msg_bdrk_01UjHdmSztrL7QYYm7CKBDFB",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 19,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 0,
      "ephemeral_1h_input_tokens": 0
    },
    "output_tokens": 4
  }
}

Confronto con l’endpoint compatibile con OpenAI

Funzionalità	Anthropic Messages (`/v1/messages`)	Compatibile con OpenAI (`/v1/chat/completions`)
Ragionamento adattivo	`thinking` con `type: "adaptive"` e `output_config.effort`	Non disponibile
Caching del Prompt	`cache_control` sui blocchi di contenuto	Non disponibile
Controllo dell’effort	`output_config.effort`	Non disponibile
Recupero/ricerca web	Strumenti server (`web_fetch`, `web_search`)	Non disponibile
Header di autenticazione	`x-api-key` o `Bearer`	Solo `Bearer`
Formato della risposta	Formato Anthropic (blocchi `content`)	Formato OpenAI (`choices`, `message`)
Modelli	Solo Claude	Multi-provider (GPT, Claude, Gemini, ecc.)

Autorizzazioni

x-api-key

string

header

obbligatorio

Your CometAPI key passed via the x-api-key header. Authorization: Bearer $COMETAPI_KEY is also supported.

Intestazioni

anthropic-version

string

predefinito:2023-06-01

The Anthropic API version to use. Defaults to 2023-06-01.

Esempio:

"2023-06-01"

anthropic-beta

string

Comma-separated list of beta features to enable. Examples: max-tokens-3-5-sonnet-2024-07-15, pdfs-2024-09-25, output-128k-2025-02-19.

Corpo

application/json

model

string

obbligatorio

The Claude model to use. See the Models page for available Claude model IDs.

Esempio:

"claude-sonnet-5"

messages

object[]

obbligatorio

The conversation messages. Must alternate between user and assistant roles. Each message's content can be a string or an array of content blocks (text, image, document, tool_use, tool_result). There is a limit of 100,000 messages per request.

Show child attributes

max_tokens

integer

obbligatorio

The maximum number of tokens to generate. The model may stop before reaching this limit. When using thinking, the thinking tokens count towards this limit.

Intervallo richiesto: x >= 1

Esempio:

1024

system

System prompt providing context and instructions to Claude. Can be a plain string or an array of content blocks (useful for prompt caching).

temperature

number

predefinito:1

Model-dependent sampling control. Many newer Claude models reject non-default temperature values on the Messages API. Omit this field unless you have verified that the selected model accepts it; if the model returns an unsupported or deprecated-parameter error, remove the field instead of substituting another sampling value.

Intervallo richiesto: 0 <= x <= 1

Esempio:

1

top_p

number

Model-dependent nucleus sampling control. Many newer Claude models reject non-default top_p values on the Messages API. Omit this field unless you have verified support for the selected model. Do not set temperature and top_p together.

Intervallo richiesto: 0 <= x <= 1

Esempio:

1

top_k

integer

Model-dependent top-k sampling control. Many newer Claude models reject non-default top_k values on the Messages API. Omit this field unless you have verified support for the selected model.

Intervallo richiesto: x >= 0

Esempio:

0

stream

boolean

predefinito:false

If true, stream the response incrementally using Server-Sent Events (SSE). Events include message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop.

stop_sequences

string[]

Custom strings that cause the model to stop generating when encountered. The stop sequence is not included in the response.

thinking

object

Controls Claude thinking when the selected model supports a configurable thinking mode. For newer adaptive-thinking models, use {"type":"adaptive"} with output_config.effort, or omit thinking when adaptive thinking is already the model default. Manual {"type":"enabled","budget_tokens":...} is supported only by older models and is rejected by newer Claude models.

Show child attributes

tools

object[]

Tools the model may use. Supports client-defined functions, web search (web_search_20250305), web fetch (web_fetch_20250910), code execution (code_execution_20250522), and more.

Show child attributes

tool_choice

object

Controls how the model uses tools.

Show child attributes

metadata

object

Request metadata for tracking and analytics.

Show child attributes

output_config

object

Configuration for response effort and output format. Field support depends on the selected Claude model.

Show child attributes

service_tier

enum<string>

The service tier to use. auto tries priority capacity first, standard_only uses only standard capacity.

Opzioni disponibili:

auto,

standard_only

Risposta

200 - application/json

Successful response. When stream is true, the response is a stream of SSE events.

string

Unique identifier for this message (e.g., msg_01XFDUDYJgAACzvnptvVoYEL).

type

enum<string>

Always message.

Opzioni disponibili:

message

role

enum<string>

Always assistant.

Opzioni disponibili:

assistant

content

object[]

The response content blocks. May include text, thinking, tool_use, and other block types.

Show child attributes

model

string

The specific model version that generated this response, such as claude-sonnet-5.

stop_reason

enum<string>

Why the model stopped generating. refusal can be returned as a successful HTTP response when the model declines a request.

Opzioni disponibili:

end_turn,

max_tokens,

stop_sequence,

tool_use,

pause_turn,

refusal

stop_sequence

string | null

The stop sequence that caused the model to stop, if applicable.

usage

object

Token usage statistics.

Show child attributes

Crea una risposta del modello

Generare contenuto

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.cometapi.com",
    api_key=os.environ["COMETAPI_KEY"],
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "Hello, world"}
    ],
)

print(message.content[0].text)

{
  "id": "<string>",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "text": "<string>",
      "thinking": "<string>",
      "signature": "<string>",
      "id": "<string>",
      "name": "<string>",
      "input": {}
    }
  ],
  "model": "<string>",
  "stop_sequence": "<string>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "cache_creation_input_tokens": 123,
    "cache_read_input_tokens": 123,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 123,
      "ephemeral_1h_input_tokens": 123
    },
    "output_tokens_details": {
      "thinking_tokens": 123
    }
  }
}

Moderazione dei contenuti

Chiavi API

Guida rapida

Controllare l’adaptive thinking

Memorizzare nella cache i prompt

Trasmettere le risposte in Streaming

Controllare l’effort

Usare gli strumenti server

Esempio di risposta

Confronto con l’endpoint compatibile con OpenAI

Autorizzazioni

Intestazioni

Corpo

Risposta

​Guida rapida

​Controllare l’adaptive thinking

​Memorizzare nella cache i prompt

​Trasmettere le risposte in Streaming

​Controllare l’effort

​Usare gli strumenti server

​Esempio di risposta

​Confronto con l’endpoint compatibile con OpenAI

Autorizzazioni

Intestazioni

Corpo

Risposta

Guida rapida

Controllare l’adaptive thinking

Memorizzare nella cache i prompt

Trasmettere le risposte in Streaming

Controllare l’effort

Usare gli strumenti server

Esempio di risposta

Confronto con l’endpoint compatibile con OpenAI