Messages API

Use this endpoint for clients that expect the Anthropic Messages format. The examples below cover text requests. Compatibility does not imply every upstream feature is available.

1. Set your API key

Create an API key and add balance in the AsterWise app. In your terminal, replace the placeholder:

export ASTER_API_KEY='your AsterWise API key'

2. Send a request

POST https://api.asterwise.dev/v1/messages

curl --include https://api.asterwise.dev/v1/messages \
  -H "x-api-key: $ASTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "aster-code",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Reply with hello."
    }
  ],
  "stream": false
}'

--include displays response headers as well as the body. Omit it if you want only JSON. Keep your API key private.

Request fields

Field	Required?	Meaning
`model`	Required	`aster-code` or `aster-work`.
`messages`	Required	User and assistant conversation turns. Use a string for simple text content.
`system`	Optional	Top-level instructions; do not add them as a system-role entry in `messages`.
`max_tokens`	Optional; explicit in this example	A positive output-token cap within the model’s supported limit. If omitted, AsterWise applies its default.
`stream`	Optional	`false` returns JSON; `true` returns server-sent events. Defaults to `false`.

The example cap of 1,024 tokens limits this response’s length. It is not the model’s maximum context window or a rate limit.

Generation controls

Field	Type	Supported use
`thinking`	object	Route-specific thinking configuration; not interchangeable with effort.
`output_config`	object	Use `{"effort":"low"}` to select a supported effort.
`temperature`, `top_p`	number	Optional sampling controls; no universal gateway default.
`tools`	array	Named tools with `input_schema`, rather than OpenAI’s nested `function` shape.
`tool_choice`	object	`{"type":"auto"}` works on both baselines; other choices are route-specific.

thinking configures thinking behavior; output_config.effort selects effort. Code supports low / high; Work also supports minimal, medium, and xhigh. The example selects effort without prescribing a separate thinking budget. Top-level reasoning and reasoning_effort are not Messages fields. For defaults, unavailable controls, tool-choice restrictions, and the DeepSeek sampling no-op exception, see parameters and model compatibility.

Reasoning and tool example

Use this JSON body with the endpoint and authentication headers above. It illustrates the supported request shape; it is not a new live-provider acceptance result. Automatic tool selection allows the model to answer without calling the tool.

{
  "model": "aster-code",
  "messages": [
    {
      "role": "user",
      "content": "Check the status of build 42."
    }
  ],
  "output_config": {
    "effort": "low"
  },
  "max_tokens": 4096,
  "tools": [
    {
      "name": "get_build_status",
      "description": "Read a build status.",
      "input_schema": {
        "type": "object",
        "properties": {
          "build_id": {
            "type": "string"
          }
        },
        "required": [
          "build_id"
        ]
      }
    }
  ],
  "tool_choice": {
    "type": "auto"
  }
}

Your application executes get_build_status when requested. Append the assistant content containing tool_use, then a user message containing tool_result with the matching tool_use_id. Preserve the rest of the supplied conversation and supported thinking blocks.

3. Read the response

Illustrative text-only response, checked against AsterWise’s response handling. IDs, answer text, and token counts below are examples, not a captured production request. Additional fields may be present.

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "aster-code",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 3
  }
}

Read text blocks in content: each block with type: "text" has a text field. Other blocks, such as tool requests, can also appear. stop_reason: "end_turn" indicates a normal completed turn. max_tokens indicates that the response reached its output cap. usage reports token counts, not a dollar charge.

Streaming

Change "stream": false to "stream": true in the request above and add --no-buffer to curl. Read the response as server-sent events (SSE), not as one JSON document. The following is an abbreviated example:

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello!"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":3}}

event: message_stop
data: {"type":"message_stop"}

Append delta.text for text_delta content events. Track input usage from message_start and final output usage from message_delta. This excerpt omits the opening message and content-block events; handle the full lifecycle in your client.

Errors

Gateway authentication and request-validation errors before streaming starts use an HTTP error status and the JSON format below. Malformed JSON, oversized bodies, or proxy errors can have a different response format; check the status and content type before parsing. For example, an invalid key returns 401:

{
  "type": "error",
  "error": {
    "type": "invalid_api_key",
    "message": "invalid_api_key"
  }
}

This is AsterWise’s shared gateway error format, including on the OpenAI-compatible endpoints. Handle error.type rather than assuming an upstream error schema.

HTTP status	Example error type	What to do
401	`invalid_api_key`	Check or replace the API key.
402	`insufficient_funds`	Add account balance.
429	`daily_limit_reached`	Review account spending controls.
429	`concurrency_limit`	Wait for existing requests to finish.
400	Request validation error	Correct the request fields before retrying.
502	`provider_empty_response`	See empty-response guidance; consider a larger output-token limit or lower reasoning effort.
503	Service unavailable	Check Usage, then retry temporary failures with a short delay.

AsterWise currently has no per-minute request or token rate limits. A 429 can still indicate a spending or simultaneous-request control. Once an SSE stream has started, an error may arrive as an error event rather than a new HTTP status. Do not treat HTTP 200 alone as a completed response. Save the x-request-id response header when present, and check Usage if the connection ends unexpectedly. See troubleshooting and usage and billing.

Get started

Connect your tools

API guides

Account and support

1. Set your API key

2. Send a request

Request fields

Generation controls

Reasoning and tool example

3. Read the response

Streaming

Errors

​1. Set your API key

​2. Send a request

​Request fields

​Generation controls

​Reasoning and tool example

​3. Read the response

​Streaming

​Errors

1. Set your API key

2. Send a request

Request fields

Generation controls

Reasoning and tool example

3. Read the response

Streaming

Errors