Messages API — POST /v1/messages | Anthropic Format

The Messages endpoint lets you point codebases that use the Anthropic SDK directly at Piramyd without changing your message structure. It accepts the Anthropic request format — including the top-level system field and Anthropic-style message objects — and returns a response shaped to the Anthropic specification. This means you can run Claude models (and any other Piramyd-hosted model) through your existing Anthropic SDK integration by changing only the base_url.

Use the official Anthropic Python or JavaScript SDK and set its base_url to https://api.piramyd.cloud/v1. Your API key, message format, and response parsing code remain unchanged.

Endpoint

POST https://api.piramyd.cloud/v1/messages

Authentication

The Messages endpoint accepts both standard Piramyd bearer tokens and the x-api-key header used by the Anthropic SDK. Use whichever form your integration already expects.

POST /v1/messages HTTP/1.1
Host: api.piramyd.cloud
Authorization: Bearer sk-YOUR_KEY
Content-Type: application/json

POST /v1/messages HTTP/1.1
Host: api.piramyd.cloud
x-api-key: sk-YOUR_KEY
Content-Type: application/json

Request Parameters

string

required

The model ID to use. Retrieve valid IDs from GET /v1/models. Example: claude-opus-4.8.

array

required

The conversation history as an array of message objects. Each object contains:

role — "user" or "assistant"
content — a string, or an array of typed content blocks (e.g. text, image) for multimodal messages

Do not include system messages here; use the top-level system field instead.

string

The system prompt. This is a top-level field in Anthropic format — not a message inside the messages array.

integer

required

Maximum number of tokens to generate. This field is required in Anthropic format (unlike Chat Completions where it has a default). Set it explicitly to avoid unexpected truncation.

float

Sampling temperature between 0 and 1 (Anthropic range). Lower values produce more focused output.

boolean

default:"false"

Set to true to receive the response as a stream of Anthropic-format SSE events.

Request Examples

import anthropic

# Point the SDK at Piramyd — no other changes needed
client = anthropic.Anthropic(
    api_key="sk-YOUR_KEY",
    base_url="https://api.piramyd.cloud/v1",
)

message = client.messages.create(
    model="claude-opus-4.8",
    system="You are a helpful coding assistant.",
    messages=[
        {"role": "user", "content": "Explain async/await in Python."}
    ],
    max_tokens=1200,
    temperature=0.2,
)

print(message.content[0].text)

curl https://api.piramyd.cloud/v1/messages \
  -H "x-api-key: sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4.8",
    "system": "You are a helpful coding assistant.",
    "messages": [
      {"role": "user", "content": "Explain async/await in Python."}
    ],
    "max_tokens": 1200,
    "temperature": 0.2,
    "stream": false
  }'

Response Shape

The response follows the Anthropic Messages response format.

string

Unique identifier for this message, prefixed with msg_.

string

Always "message".

string

Always "assistant".

array

Array of content blocks generated by the model. For standard text responses, this contains one block with type: "text" and a text field.

Show content block fields

string

The content block type. "text" for standard text output; "tool_use" when the model is calling a tool.

string

The generated text. Present when type is "text".

string

The exact model ID that generated the response.

string

Why the model stopped generating:

"end_turn" — natural end of output
"max_tokens" — hit the max_tokens limit
"tool_use" — the model is requesting a tool call

object

Token counts for this request.

Show usage fields

integer

Tokens in the input (system + messages).

integer

Tokens generated in the response.

Example response

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "In Python, `async` and `await` are used to write asynchronous code..."
    }
  ],
  "model": "claude-opus-4.8",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 24,
    "output_tokens": 210
  }
}

Inference

Models

Web Intelligence

Account

Messages API — POST /v1/messages | Anthropic Format

Endpoint

Authentication

Request Parameters

Request Examples

Response Shape

​Endpoint

​Authentication

​Request Parameters

​Request Examples

​Response Shape

Endpoint

Authentication

Request Parameters

Request Examples

Response Shape