Claude API for measuring a request before generation

Originally published on Medium

A support team may assemble a prompt from a system policy, a PDF manual, the latest customer message, and several tool definitions. The final JSON can be much larger than the text visible in the chat box. Sending it first and measuring later is like weighing a parcel after it has left the warehouse.

The Claude API on Ace Data Cloud gives us a useful preflight step. We can count the input tokens in the complete request at zero credits, then submit the message through the native Claude format. That makes token budgeting part of request construction instead of a surprise in the usage record.

Choose the native shape or the familiar chat shape

Claude AI on Ace Data Cloud exposes two generation formats and one counting operation.

The Claude Messages API uses Anthropic's native message structure at POST /claude/messages. It accepts model, messages, and max_tokens as the core generation fields. It also supports a top-level system prompt, streaming, tools, images, documents, prompt caching, and thinking configuration.

The Claude Chat Completions API is available at POST /claude/chat/completions. Its OpenAI-compatible shape is useful when an application already expects chat completions.

The preflight endpoint is POST /claude/messages/count_tokens. Its request mirrors the native Messages input closely, so we can count a payload containing much more than a plain string.

Send a native message

The smallest useful native request contains a model, an output limit, and a user message. Authentication uses an Ace Data Cloud bearer token.

curl -X POST 'https://api.acedata.cloud/claude/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

A non-streaming response has the native Claude message shape:

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

id uniquely identifies the returned message. type is message, and role is assistant. content is an array because a reply can contain typed blocks rather than one undifferentiated string. Here the block has type: text, and text contains the answer.

model records which model handled the request. stop_reason explains why generation ended. end_turn means the model completed its turn. Other documented values include max_tokens, stop_sequence, tool_use, pause_turn, refusal, and model_context_window_exceeded. stop_sequence is null here because no custom sequence ended the reply.

usage.input_tokens reports uncached input tokens, while usage.output_tokens reports generated tokens. Responses can also report cache creation and cache read token counts when caching is involved. Non-streaming responses may include the cost recorded by Ace Data Cloud.

Count the payload that will actually be sent

The token counter becomes useful when the payload grows. We can send model and messages, then include the same optional structures our generation request will use. The schema supports system, tools, tool_choice, thinking, and cache_control.

Message content can also include typed blocks. Image blocks accept Base64 data or a URL, with JPEG, PNG, GIF, and WebP media types. Document blocks can carry a Base64 PDF, a PDF URL, plain text, or content made from text and image blocks. The token count therefore reflects the assembled API request rather than a rough character estimate.

curl -X POST 'https://api.acedata.cloud/claude/messages/count_tokens' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-opus-4-8",
    "system": "Answer from the supplied reference material.",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the deployment rules."
      }
    ]
  }'

The successful response contains input_tokens, an integer with the calculated input count. The endpoint does not generate assistant text. We bill this operation at 0 credits. The Claude service itself includes 1.0 free credit, while generation is billed in credits according to the selected model and measured token usage.

For a current price reference, claude-opus-5 is listed at 10.5124 credits per 1 million input tokens and 52.5618 credits per 1 million output tokens. Its listed capabilities include reasoning and vision. Prices differ by model, so production code should read the current catalog rather than copy one model's rate into a permanent constant.

The counter understands more than text

A common token helper accepts a string and returns an estimate. This endpoint accepts the request structures that materially affect a Claude call. We can count tool definitions before exposing them to the model. We can include a document block with optional title, context, and citation settings. We can represent an image as a URL or Base64 source. We can also include cache controls.

Top-level cache_control places a cache breakpoint at the last cacheable block. Its ttl supports 5m, which is the default, and 1h. For precise placement, cache control can be attached to text, image, document, tool-use, tool-result blocks, or tool definitions. Generation usage then distinguishes cache_creation_input_tokens from cache_read_input_tokens.

Thinking settings belong in the same planning process. Current models can use thinking.type: adaptive, with output_config.effort controlling reasoning effort. When display is summarized, the response can contain a readable thinking summary. When it is omitted, reasoning still occurs, but returned thinking text is empty and the opaque signature remains available for later turns. Display selection does not reduce billing for thinking tokens.

Put preflight counting in the request path

We can build one payload object, send its countable fields to /claude/messages/count_tokens, compare input_tokens with our application budget, and then send the generation request to /claude/messages. If the count is too high, the application can shorten retrieved context or remove unnecessary tool descriptions before it pays for generation.

Keep max_tokens as an explicit generation limit, preserve prior assistant and user turns in order, and pass returned thinking blocks and signatures back unchanged when the workflow requires them. For streaming interfaces, set stream to true and consume Server-Sent Events such as message_start, content_block_delta, message_delta, and message_stop.

Create one token in the Ace Data Cloud console, use the free counter on the full payload your application has assembled, and send the approved structure to the native Messages endpoint. The count request costs zero, so it can sit directly in the validation path instead of being reserved for occasional debugging.

Sources: Anthropic Messages API, Anthropic token counting

Tags: Claude API, Anthropic, API Development, Artificial Intelligence, Software Engineering