Text Generation

POST /v1/messages

Anthropic Messages-style text generation endpoint.

Generate text with an Anthropic Messages-compatible request and response format.

Description

This endpoint accepts Anthropic-style message payloads and forwards them through APIFree’s unified model platform. It is suitable for assistants, chat applications, agent loops, and other conversational workflows that already use the Messages protocol.

Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the format `Bearer YOUR_API_KEY`.
`anthropic-version`	string	No	Anthropic protocol version header to forward upstream.
`anthropic-beta`	string	No	Optional beta feature header to forward upstream.

Request body parameters

Name	Type	Required	Description
`model`	string	Yes	Model ID to use for generation.
`messages`	array	Yes	Ordered list of conversation messages.
`system`	string / array	No	System instruction content.
`max_tokens`	integer	No	Maximum number of tokens to generate.
`temperature`	number	No	Sampling temperature.
`top_p`	number	No	Nucleus sampling parameter.
`stream`	boolean	No	Whether to return SSE streaming events.
`tools`	array	No	Tool definitions available to the model.
`tool_choice`	object / string	No	Tool calling strategy.
`metadata`	object	No	Optional metadata for your own tracking.

`messages` item

Each item in messages is an object like:

{
  "role": "user",
  "content": "Write a concise product summary for an AI gateway."
}

Supported models

Model
`claude-sonnet-4`
`claude-opus-4.6`
`claude-sonnet-4.6`
`claude-opus-4.5`
`claude-sonnet-4.5`
`claude-haiku-4.5`

Example request

cURL

curl https://api.apifree.ai/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "Summarize the benefits of a unified model API in one paragraph."
      }
    ]
  }'

Response schema

A successful non-stream response typically includes:

Field	Type	Description
`id`	string	Unique response identifier.
`type`	string	Response object type.
`role`	string	Usually `assistant`.
`content`	array	Generated content blocks.
`model`	string	Model used to generate the response.
`stop_reason`	string	Why generation stopped.
`usage`	object	Token usage information.

Example response:

{
  "id": "msg_123",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4",
  "content": [
    {
      "type": "text",
      "text": "A unified model API reduces integration cost by giving teams one endpoint for authentication, routing, billing, and observability across multiple providers."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 24,
    "output_tokens": 36
  }
}

Streaming

If stream is true, the endpoint returns Anthropic-style SSE events. Your client should consume the stream incrementally until the terminal event is received.

Errors

Errors are returned as JSON error objects. Typical cases include:

Missing or invalid model
Invalid JSON request body
Authentication failure
Upstream request failure