> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refuseless.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages (Anthropic)

> POST /v1/messages — Anthropic Messages API on the same models.

# POST /v1/messages

The Anthropic Messages API, translated onto the same lineup, keys, and billing
as chat completions. Use it when your SDK or agent (Anthropic SDKs, Claude
Code, and other Anthropic-native tools) speaks Messages instead of OpenAI chat.

```
POST https://api.refuseless.com/v1/messages
```

Each request runs as one chat generation. Model ids, billing, and error
statuses match `/v1/chat/completions`. Errors come back in the Anthropic
shape.

## Authentication

Send your key either way:

* `x-api-key: abl_…` (what Anthropic SDKs send)
* `Authorization: Bearer abl_…`

`anthropic-version` and `anthropic-beta` headers are accepted and ignored.
This endpoint takes API keys only, not console sessions.

## Request

| Field | Type | Required | Notes |
| - | - | - | - |
| `model` | string | Yes | Catalog id, e.g. `glm-5.3-abliterated` |
| `messages` | array | Yes | `user` / `assistant` turns. `content` is a string or an array of blocks. |
| `system` | string / array | No | System prompt. Text blocks are joined. |
| `max_tokens` | number | No | Output limit. Defaults to the model's max output, else its context minus the prompt. |
| `stream` | boolean | No | Default `false`. `true` returns Anthropic SSE events. |
| `temperature` / `top_p` / `top_k` | number | No | Passed through where the model supports them |
| `stop_sequences` | string\[] | No | Up to 4 are used |
| `tools` | array | No | Custom tools with `input_schema`. Counted toward input reservation. |
| `tool_choice` | object | No | `auto`, `any`, `none`, or `{"type": "tool", "name": "…"}`. `disable_parallel_tool_use` is honored. |
| `thinking` | object | No | Mapped to a reasoning effort. See [Thinking and effort](#thinking-and-effort). |
| `output_config.effort` | string | No | Mapped to a reasoning effort. Wins over `thinking`. |
| `reasoning_effort` | string | No | Our native field: `off`, `low`, `high`, or `max`. Wins over both fields above. See [Reasoning](https://docs.refuseless.com/guides/reasoning.md). |

Other fields (`metadata`, `service_tier`, `cache_control`, and so on) are
accepted and ignored.

### Content blocks

| Block | Where | Handling |
| - | - | - |
| `text` | user, assistant | Supported |
| `image` | user, `tool_result` | `base64` sources, on models that take image input. `url` sources are not fetched: the image is left out and the request still succeeds. |
| `document` | user, `tool_result` | Plain-text sources only (`text` or `content`). PDF and file sources return `400`. |
| `tool_use` | assistant | Supported |
| `tool_result` | user | Supported. `is_error: true` prefixes the result with `Error:`. |
| `thinking` / `redacted_thinking` | assistant | Dropped from history. Their signatures mean nothing to these models. |

Turns with `role: "system"` or `"developer"` inside `messages` are folded into
the system prompt instead of being rejected.

Anthropic-hosted server tools (`web_search_*`, `code_execution_*`, and others
with no `input_schema`) are skipped. These models cannot run them.

## Non-streamed response

```json theme={null}
{
  "id": "msg_4f1c2a9e8b7d6c5a4f3e2d1c",
  "type": "message",
  "role": "assistant",
  "model": "glm-5.3-abliterated",
  "content": [
    { "type": "thinking", "thinking": "…", "signature": "" },
    { "type": "text", "text": "…" }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 64,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}
```

* `thinking` blocks appear on reasoning models. `signature` is always empty.
* Tool calls come back as `{ "type": "tool_use", "id": "…", "name": "…", "input": {…} }` blocks.
* `stop_reason` is `end_turn`, `max_tokens`, or `tool_use`. It is never
  `stop_sequence`, and `stop_sequence` is always `null`.
* `cache_read_input_tokens` is set when prompt caching applies. As in the
  Anthropic API, `input_tokens` does not include cached tokens.
  `cache_creation_input_tokens` is always `0`.

## Streaming

Set `stream: true` for the standard Anthropic event sequence:

`message_start` → `ping` → `content_block_start` → `content_block_delta`
(×N) → `content_block_stop` → … → `message_delta` (with `stop_reason` and
final `usage`) → `message_stop`.

* Text (`text_delta`) and thinking (`thinking_delta`) stream live.
* Tool calls are buffered. Each `tool_use` block is sent whole at the end,
  as one `input_json_delta` holding the complete arguments.
* `usage` in `message_start` is an estimate. Use the `message_delta` usage
  for real counts.
* On long waits the server sends keep-alives before the first event, so
  proxies do not time out the connection.
* A failure mid-stream sends an `error` event, then the stream closes.

```bash theme={null}
curl -N https://api.refuseless.com/v1/messages \
  -H "x-api-key: $REFUSELESS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-abliterated",
    "max_tokens": 512,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a tight system prompt."}]
  }'
```

## Thinking and effort

Anthropic thinking settings map to our reasoning levels:

| You send | Effort |
| - | - |
| `output_config.effort: "low"` | `low` |
| `output_config.effort: "medium"` or `"high"` | `high` |
| `output_config.effort: "xhigh"` or `"max"` | `max` |
| `thinking: {"type": "disabled"}` | `off` |
| `thinking: {"type": "enabled"}`, `budget_tokens` under 8,000 | `low` |
| `thinking: {"type": "enabled"}`, `budget_tokens` 8,000 to 23,999 | `high` |
| `thinking: {"type": "enabled"}`, `budget_tokens` 24,000 or more | `max` |
| `thinking: {"type": "adaptive"}` or nothing | Model default |

The result is fitted to the levels the model offers, so a thinking setting
never causes a `400`. If you ask for `off` and the model cannot turn
reasoning off, the model default applies. Otherwise you get the closest level
at or below your request, else the lowest one above it. `budget_tokens` is
not a hard limit on thinking length.

If you send `reasoning_effort` yourself, it is not fitted. It is checked as
strictly as on `/v1/chat/completions`.

## Example

```bash theme={null}
curl https://api.refuseless.com/v1/messages \
  -H "x-api-key: $REFUSELESS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-abliterated",
    "max_tokens": 512,
    "system": "You are terse.",
    "messages": [{"role": "user", "content": "Write a tight system prompt."}]
  }'
```

With the Anthropic SDK, set the base URL to the host **without** `/v1`. The
SDK adds `/v1/messages` itself. See [SDKs](https://docs.refuseless.com/sdks.md#anthropic-sdk).

## Count tokens

```
POST https://api.refuseless.com/v1/messages/count_tokens
```

Takes the same body as `/v1/messages` and returns:

```json theme={null}
{ "input_tokens": 42 }
```

This is an estimate: the same one used to size the credit hold. It is free.
Nothing is billed and no model runs.

## Errors

Errors use the Anthropic shape:

```json theme={null}
{
  "type": "error",
  "error": { "type": "invalid_request_error", "message": "model: Field required." }
}
```

| Status | `error.type` | When |
| - | - | - |
| `400` | `invalid_request_error` | Missing `model`, bad `messages`, PDF document, invalid JSON |
| `401` | `authentication_error` | Missing or invalid key |
| `402` | `billing_error` | Out of credits |
| `403` | `permission_error` | Model not available on your plan |
| `404` | `not_found_error` | Unknown model |
| `405` | `invalid_request_error` | Method other than `POST` |
| `413` | `request_too_large` | Body too large |
| `429` | `rate_limit_error` | Model busy or warming, or a plan limit hit. Honor `retry-after`. |
| `503` | `overloaded_error` | Model or gateway unavailable |
| other | `api_error` | Generation failed |

Full table of causes: [Errors](https://docs.refuseless.com/guides/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.