Create a Message - CometAPI Documentation

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 supports the Anthropic Messages API natively, giving you direct access to Claude models with Anthropic-specific features. Use this endpoint for Claude capabilities like adaptive thinking, prompt caching, and effort control.

Use the official Anthropic Messages API reference as the authoritative source for the complete parameter list, response schema, and Claude-specific behavior. This CometAPI page explains how to send that request shape through CometAPI.

Anthropic request parameters and response fields can change as Claude features evolve. Check the Anthropic Messages API documentation for the latest complete parameter list and provider-specific behavior.

Many newer Claude models reject non-default temperature, top_p, and top_k values on the Messages API. Omit these sampling fields unless you have verified support for the selected model. If a model returns an unsupported or deprecated-parameter error, remove the field from the request.

Both x-api-key and Authorization: Bearer headers are supported for authentication. The official Anthropic SDKs use x-api-key by default.

Quick start

To use the official Anthropic SDK with CometAPI, set the 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);

Control adaptive thinking

Use adaptive thinking with output_config.effort to control how much work Claude applies to a response. Newer Claude models reject the legacy manual thinking shape 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)

Thinking tokens count toward your max_tokens limit. Set max_tokens high enough for both thinking and the final answer when you use higher effort levels.

Cache prompts

To reduce latency and cost on subsequent requests, cache large system prompts or conversation prefixes. Add cache_control to content blocks that should be cached:

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..."}],
)

Cache usage is reported in the response usage field:

cache_creation_input_tokens — tokens written to cache (billed at a higher rate)
cache_read_input_tokens — tokens read from cache (billed at a reduced rate)

Prompt caching requires a minimum of 1,024 tokens in the cached content block. Content shorter than this will not be cached.

Stream responses

To stream responses using Server-Sent Events (SSE), set stream: true. Events arrive in this order:

message_start — contains the message metadata and initial usage
content_block_start — marks the beginning of each content block
content_block_delta — incremental text chunks (text_delta)
content_block_stop — marks the end of each content block
message_delta — final stop_reason and complete usage
message_stop — signals the end of the 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="")

Control effort

To control how much effort Claude puts into generating a response, use 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"
)

Use server tools

Claude supports server-side tools that run on Anthropic’s infrastructure:

Web Fetch
Web Search

Fetch and analyze content from URLs:

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}
    ],
)

Search the web for real-time information:

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}
    ],
)

Response example

A typical response from CometAPI’s Anthropic endpoint:

{
  "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
  }
}

Compare with OpenAI-compatible endpoint

Feature	Anthropic Messages (`/v1/messages`)	OpenAI-Compatible (`/v1/chat/completions`)
Adaptive thinking	`thinking` with `type: "adaptive"` and `output_config.effort`	Not available
Prompt caching	`cache_control` on content blocks	Not available
Effort control	`output_config.effort`	Not available
Web fetch/search	Server tools (`web_fetch`, `web_search`)	Not available
Auth header	`x-api-key` or `Bearer`	`Bearer` only
Response format	Anthropic format (`content` blocks)	OpenAI format (`choices`, `message`)
Models	Claude only	Multi-provider (GPT, Claude, Gemini, etc.)

Authorizations

x-api-key

string

header

required

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

Headers

anthropic-version

string

default:2023-06-01

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

Example:

"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.

Body

application/json

model

string

required

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

Example:

"claude-sonnet-5"

messages

object[]

required

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

required

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.

Required range: x >= 1

Example:

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

default: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.

Required range: 0 <= x <= 1

Example:

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.

Required range: 0 <= x <= 1

Example:

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.

Required range: x >= 0

Example:

0

stream

boolean

default: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.

Available options:

auto,

standard_only

Response

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.

Available options:

message

role

enum<string>

Always assistant.

Available options:

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.

Available options:

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

Create a model response

Generate content

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
    }
  }
}

​Quick start

​Control adaptive thinking

​Cache prompts

​Stream responses

​Control effort

​Use server tools

​Response example

​Compare with OpenAI-compatible endpoint

Authorizations

Headers

Body

Response

Quick start

Control adaptive thinking

Cache prompts

Stream responses

Control effort

Use server tools

Response example

Compare with OpenAI-compatible endpoint