Responses API

Use this endpoint when your application or SDK expects the OpenAI Responses 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/responses

curl --include https://api.asterwise.dev/v1/responses \
  -H "Authorization: Bearer $ASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "aster-code",
  "input": "Reply with hello.",
  "max_output_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`.
`input`	Required	A text string for a simple prompt, or supported structured input items.
`instructions`	Optional	Instructions for how the model should respond.
`max_output_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
`reasoning`	object	Use `{"effort":"low"}` or another supported effort.
`temperature`, `top_p`	number	Optional sampling controls; no universal gateway default.
`tools`	array	Function tools with `type`, `name`, and `parameters` at the same level.
`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.

Use reasoning.effort, not a top-level reasoning_effort, thinking, or output_config. Code supports low / high; Work also supports minimal, medium, and xhigh. Arbitrary reasoning budget or exclusion fields are not a universal supported contract. 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",
  "input": "Check the status of build 42.",
  "reasoning": {
    "effort": "low"
  },
  "max_output_tokens": 4096,
  "tools": [
    {
      "type": "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. Include the previous input/output items and a function_call_output item with the matching call_id in the next input. Send explicit history: non-null previous_response_id and conversation are not supported.

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": "resp_example",
  "object": "response",
  "model": "aster-code",
  "status": "completed",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 3,
    "total_tokens": 15
  }
}

Read the output array. For each item with type: "message", collect content blocks with type: "output_text" and read their text fields. Do not assume the first output item is always text: tool calls and other items can also appear. status: "completed" identifies a completed response. Check for an incomplete result before treating the answer as finished. usage reports input and output tokens; it is 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: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_example","output_index":0,"content_index":0,"delta":"Hello!"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_example","object":"response","model":"aster-code","status":"completed","output":[{"id":"msg_example","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Hello!","annotations":[]}]}],"usage":{"input_tokens":12,"output_tokens":3,"total_tokens":15}}}

Append text from response.output_text.delta. Use the terminal response event to inspect status and usage. Other lifecycle and tool events can appear; this excerpt omits them.

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