Chat Completions API

Use this endpoint for clients that expect the OpenAI Chat Completions 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/chat/completions

curl --include https://api.asterwise.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "aster-code",
  "messages": [
    {
      "role": "user",
      "content": "Reply with hello."
    }
  ],
  "max_completion_tokens": 1024,
  "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	Conversation messages, each with a role and content. Include earlier turns when continuing a conversation.
`max_completion_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. max_tokens is also accepted as an alternative output cap. Do not send it together with max_completion_tokens.

Generation controls

Field	Type	Supported use
`reasoning_effort`	string	Optional effort: Code `low` / `high`; Work also supports `minimal`, `medium`, `xhigh`.
`temperature`, `top_p`	number	Optional sampling controls; no universal gateway default.
`frequency_penalty`, `presence_penalty`	number	Optional repetition controls on baseline routes.
`tools`	array	Function tools with `type: "function"` and a nested `function` object.
`tool_choice`	string or object	`"auto"` works on both baselines; other choices are route-specific.
`parallel_tool_calls`	boolean	Optional parallel-tool control on eligible baseline routes.

reasoning_effort is the documented effort selector here. A route-specific reasoning object is also recognized, but is not a universal enable/budget/exclude schema. Do not substitute Responses reasoning.effort or Messages thinking / output_config for this example. 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."
    }
  ],
  "reasoning_effort": "low",
  "max_completion_tokens": 4096,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_build_status",
        "description": "Read a build status.",
        "parameters": {
          "type": "object",
          "properties": {
            "build_id": {
              "type": "string"
            }
          },
          "required": [
            "build_id"
          ]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Your application executes get_build_status when requested. Append the assistant tool-call message and a role: "tool" message with the matching tool_call_id to messages before the next request.

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": "chatcmpl_example",
  "object": "chat.completion",
  "model": "aster-code",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 3,
    "total_tokens": 15
  }
}

For a text reply, read choices[0].message.content. Inspect finish_reason as well: stop indicates normal completion, while a length limit can produce a truncated answer. A tool request can contain message.tool_calls instead of ordinary answer text. Here, prompt_tokens means input tokens and completion_tokens means output tokens. The usage object contains 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:

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","model":"aster-code","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello!"},"finish_reason":null}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","model":"aster-code","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Append text from choices[].delta.content. These are incremental pieces, not complete messages. Check the finish reason and stream termination. Usage may arrive in a separate chunk, including one with an empty choices array.

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

Chat Completions API

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