AionRouter Text Generation API Guide

Use AionRouter text APIs for conversation, drafts, summaries, coding assistance and tool-driven applications. First identify the protocol supported by your model, then supply the API URL, key and model ID. An “OpenAI compatible” client label alone does not establish support for every feature.

This guide starts with minimal requests for macOS/Linux, Windows PowerShell/CMD and Python, then explains conversation history, streaming events and connecting tools and structured output to your application.

Choose a model and protocol for your task

Define the result your task needs before choosing capabilities. Summaries must preserve key facts; order extraction needs validated fields; a coding agent may require tools, streaming and sufficient context together. Receiving text confirms only basic generation.

Open the model details from the model catalog to check endpoints, context, inputs, outputs, parameters and billing, then verify with your key. Do not infer capabilities or recommendation rankings from model names.

Choose an API

These gateway endpoints do not imply that every model or channel supports every format. Check the model's endpoint information in the Model Marketplace, then verify it with your key.

Set up your environment and make the first call

Prepare the URL, key and model

Replace the URL with the console's API root and the model with an actual ID accessible to your key.

Terminal compatibility

Use the examples for your shell: macOS/Linux use Bash or Zsh; Windows uses PowerShell or CMD. Git Bash/WSL can use the Bash examples, but run all setup and requests in the same environment. The current API root is https://test.aionrouter.io.

Windows examples explicitly use curl.exe to avoid the curl alias in Windows PowerShell 5.1. Check curl --version or curl.exe --version; --fail-with-body requires cURL 7.76.0 or later. Microsoft: curl on Windows · cURL options

Run one shell variant only. Environment variables apply to that terminal and programs started from it. In CMD, run each line separately; at the AIONROUTER_BASE_URL prompt, paste the API root shown above, without a trailing slash. Then enter the actual key, model or voice when prompted. Do not paste Bash export, backslash continuations or heredocs into CMD or PowerShell.

macOS / Linux — Bash / Zsh

export AIONROUTER_BASE_URL='https://test.aionrouter.io'
export AIONROUTER_API_KEY='替换为控制台复制的完整密钥'
export AIONROUTER_TEXT_MODEL='替换为支持 Chat Completions 的实际模型 ID'

Windows — PowerShell

$env:AIONROUTER_BASE_URL = 'https://test.aionrouter.io'
$env:AIONROUTER_API_KEY = Read-Host 'AIONROUTER_API_KEY'
$env:AIONROUTER_TEXT_MODEL = Read-Host 'AIONROUTER_TEXT_MODEL'

Windows — CMD

set "AIONROUTER_BASE_URL="
set /p "AIONROUTER_BASE_URL=AIONROUTER_BASE_URL: "
set "AIONROUTER_API_KEY="
set /p "AIONROUTER_API_KEY=AIONROUTER_API_KEY: "
set "AIONROUTER_TEXT_MODEL="
set /p "AIONROUTER_TEXT_MODEL=AIONROUTER_TEXT_MODEL: "

You can check the model list first:

macOS / Linux — Bash / Zsh

curl --fail-with-body --silent --show-error \
  "$AIONROUTER_BASE_URL/v1/models" \
  -H "Authorization: Bearer $AIONROUTER_API_KEY"

Windows — PowerShell

curl.exe --fail-with-body --silent --show-error "${env:AIONROUTER_BASE_URL}/v1/models" -H "Authorization: Bearer ${env:AIONROUTER_API_KEY}"

Windows — CMD

curl.exe --fail-with-body --silent --show-error "%AIONROUTER_BASE_URL%/v1/models" -H "Authorization: Bearer %AIONROUTER_API_KEY%"

Copy the full model name from data[].id or its detail page. Similar names may have different capabilities, prices and API restrictions; do not remove version suffixes yourself.

Generate text with Chat Completions

cURL request

macOS / Linux — Bash / Zsh

curl --fail-with-body --silent --show-error \
  "$AIONROUTER_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AIONROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$AIONROUTER_TEXT_MODEL",
  "messages": [
    {"role": "user", "content": "请用三句话说明向量数据库适合解决哪些问题。"}
  ]
}
JSON

Windows request body: text-generation-3.json

Save this JSON in the current directory as UTF-8 without BOM, replacing YOUR_... values with actual model IDs or other required values. JSON files do not expand environment variables: changing a terminal model variable does not change this file. Do not use Windows PowerShell 5.1 > to create it, because that defaults to UTF-16LE. Both Windows commands below read the same file. Microsoft: character encoding

{
  "model": "YOUR_AIONROUTER_TEXT_MODEL",
  "messages": [
    {
      "role": "user",
      "content": "请用三句话说明向量数据库适合解决哪些问题。"
    }
  ]
}

Windows — PowerShell

curl.exe --fail-with-body --silent --show-error "${env:AIONROUTER_BASE_URL}/v1/chat/completions" -H "Authorization: Bearer ${env:AIONROUTER_API_KEY}" -H 'Content-Type: application/json' --data-binary '@text-generation-3.json'

Windows — CMD

curl.exe --fail-with-body --silent --show-error "%AIONROUTER_BASE_URL%/v1/chat/completions" -H "Authorization: Bearer %AIONROUTER_API_KEY%" -H "Content-Type: application/json" --data-binary "@text-generation-3.json"

For non-streaming responses, text is normally in choices[0].message.content, with usage in usage. The following is an illustrative excerpt:

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这里是模型生成的回答。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  }
}

The sample usage numbers are not actual measurements for your request. When the model returns tool calls, content can be empty; inspect tool_calls and the finish reason too.

Python request

This example uses only the Python standard library. Save it as a file and run it from the terminal where you set the environment variables.

import json
import os
import urllib.error
import urllib.request

base_url = os.environ["AIONROUTER_BASE_URL"].rstrip("/")
payload = {
    "model": os.environ["AIONROUTER_TEXT_MODEL"],
    "messages": [
        {"role": "user", "content": "请为一款待办事项应用写一句简洁介绍。"}
    ],
}
request = urllib.request.Request(
    f"{base_url}/v1/chat/completions",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['AIONROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print("HTTP", error.code)
    print(error.read().decode("utf-8", errors="replace"))
    raise SystemExit(1)

message = result["choices"][0]["message"]
print(message.get("content") or "模型返回了非纯文本消息，请检查 tool_calls 等字段。")

Run the Python example on macOS or Windows

Save the code as example.py in UTF-8. In the terminal where you set the variables above, use python3 example.py on macOS/Linux or py -3 example.py on Windows. If the Windows launcher is unavailable but Python 3 is installed, use python example.py. The standard-library code is shared; variables set in PowerShell, CMD and WSL are not automatically shared.

The 120-second timeout is a client setting you can adjust, not a platform delivery guarantee for every model.

Establish a reproducible minimal request. After success, record the exact model ID, protocol and required parameters, then change one item at a time. Changing the model, protocol, images, tools and output controls together makes failures hard to diagnose.

Check that the result meets the task, not only that HTTP returned 200. Text may be empty, truncated or replaced by non-text content such as tool calls. Identify the response structure before displaying it, running a tool or asking for more input.

Manage conversation history and output parameters

Include history for multi-turn conversations

Chat Completions uses messages as its conversation context. Include the user and assistant messages you want to retain:

{
  "model": "YOUR_CHAT_MODEL_ID",
  "messages": [
    {"role": "user", "content": "我在设计一个面向学生的背单词应用。"},
    {"role": "assistant", "content": "可以先确定目标年级和每天的学习时间。"},
    {"role": "user", "content": "目标是高中生，每天学习十五分钟。请提出三个核心功能。"}
  ]
}

History is sent again with each request and consumes context and input usage. As conversations grow, shorten history, retain essential facts or generate summaries. Context limits depend on the model.

Common parameters and capability limits

Connect tool calls to the application

A Chat model supporting tools can return message.tool_calls with names, arguments and call IDs. Validate the arguments, run approved business actions, and return tool results with their corresponding tool_call_id.

A generated tool call does not mean the server has queried your database, executed code or performed an external action. Responses and Messages use different tool-result formats as well.

Does asking for JSON guarantee valid output?

No. Prefer a model's supported structured-output mode, then parse and validate results in your application. A prompt saying “return JSON” does not replace business-field validation.

Select useful history. Multi-turn APIs do not allow unlimited accumulation of every message. Keep recent exchanges, necessary system constraints and task facts. Summarize older material if useful, but check for lost requirements. Reduce input when model or channel limits are exceeded; increasing timeouts alone will not help.

Retrieval results do not enter context automatically. For knowledge-base answers, your application must retrieve relevant excerpts and include them with the question in a supported input format. Missing database records are not retrieved facts. Preserve source identifiers when results need citations.

Validate structured results against business rules. Use JSON Schema when supported, then check field types, enums, numeric bounds and required fields before continuing. Parseable JSON does not prove an order ID, date or conclusion is correct.

Set output limits for the task. Classification and long-form generation need different output sizes. Use fields accepted by the chosen endpoint and inspect termination reasons for truncation. Context windows, output limits and platform safety bounds are different limits.

Integrate SSE, Responses and Messages

Stream with SSE

For a model that supports streaming, set stream: true in the Chat Completions request:

macOS / Linux — Bash / Zsh

curl --fail-with-body --silent --show-error --no-buffer \
  "$AIONROUTER_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AIONROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$AIONROUTER_TEXT_MODEL",
  "messages": [
    {"role": "user", "content": "写一段介绍城市夜间骑行的短文。"}
  ],
  "stream": true
}
JSON

Windows request body: text-generation-4.json

Save this JSON in the current directory as UTF-8 without BOM, replacing YOUR_... values with actual model IDs or other required values. JSON files do not expand environment variables: changing a terminal model variable does not change this file. Do not use Windows PowerShell 5.1 > to create it, because that defaults to UTF-16LE. Both Windows commands below read the same file. Microsoft: character encoding

{
  "model": "YOUR_AIONROUTER_TEXT_MODEL",
  "messages": [
    {
      "role": "user",
      "content": "写一段介绍城市夜间骑行的短文。"
    }
  ],
  "stream": true
}

Windows — PowerShell

curl.exe --fail-with-body --silent --show-error --no-buffer "${env:AIONROUTER_BASE_URL}/v1/chat/completions" -H "Authorization: Bearer ${env:AIONROUTER_API_KEY}" -H 'Content-Type: application/json' --data-binary '@text-generation-4.json'

Windows — CMD

curl.exe --fail-with-body --silent --show-error --no-buffer "%AIONROUTER_BASE_URL%/v1/chat/completions" -H "Authorization: Bearer %AIONROUTER_API_KEY%" -H "Content-Type: application/json" --data-binary "@text-generation-4.json"

Chat Completions streams normally send SSE data: events. Read text or tool-call fragments from choices[].delta. Network chunks do not correspond one-to-one with complete events: use an SSE parser rather than treating each read as complete JSON.

If supported by the model and channel, stream_options.include_usage requests usage near the end of the stream. Missing usage after an unsupported option or interrupted connection does not mean zero usage.

Responses and Messages have different event structures. A parser that only reads choices[].delta.content cannot handle all formats. A disconnected stream also does not prove the request was unprocessed or free of charge.

Use the Responses API

Select a model supporting Responses, set AIONROUTER_RESPONSES_MODEL, and submit input:

macOS / Linux — Bash / Zsh

export AIONROUTER_RESPONSES_MODEL='替换为支持 Responses 的实际模型 ID'

curl --fail-with-body --silent --show-error \
  "$AIONROUTER_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $AIONROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$AIONROUTER_RESPONSES_MODEL",
  "input": "请把以下任务拆成三个步骤：为一个博客添加站内搜索。"
}
JSON

Windows request body: text-generation-5.json

Save this JSON in the current directory as UTF-8 without BOM, replacing YOUR_... values with actual model IDs or other required values. JSON files do not expand environment variables: changing a terminal model variable does not change this file. Do not use Windows PowerShell 5.1 > to create it, because that defaults to UTF-16LE. Both Windows commands below read the same file. Microsoft: character encoding

{
  "model": "YOUR_AIONROUTER_RESPONSES_MODEL",
  "input": "请把以下任务拆成三个步骤：为一个博客添加站内搜索。"
}

Windows — PowerShell

$env:AIONROUTER_RESPONSES_MODEL = Read-Host 'AIONROUTER_RESPONSES_MODEL'
curl.exe --fail-with-body --silent --show-error "${env:AIONROUTER_BASE_URL}/v1/responses" -H "Authorization: Bearer ${env:AIONROUTER_API_KEY}" -H 'Content-Type: application/json' --data-binary '@text-generation-5.json'

Windows — CMD

set "AIONROUTER_RESPONSES_MODEL="
set /p "AIONROUTER_RESPONSES_MODEL=AIONROUTER_RESPONSES_MODEL: "
curl.exe --fail-with-body --silent --show-error "%AIONROUTER_BASE_URL%/v1/responses" -H "Authorization: Bearer %AIONROUTER_API_KEY%" -H "Content-Type: application/json" --data-binary "@text-generation-5.json"

Raw HTTP output is in the output array. Text messages normally contain items with type: "output_text", but output can include other types. Inspect item types rather than assuming the first item is text.

Use max_output_tokens for the output limit, unlike Chat's max_tokens or max_completion_tokens. Storage, references to previous responses and built-in tools also require actual support from the selected model and channel.

Use Anthropic Messages

Messages uses Anthropic message structures. Replace the example ID with an available model supporting that format:

macOS / Linux — Bash / Zsh

curl --fail-with-body --silent --show-error \
  "$AIONROUTER_BASE_URL/v1/messages" \
  -H "x-api-key: $AIONROUTER_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "model": "YOUR_MESSAGES_MODEL_ID",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "请解释幂等请求，并举一个支付接口之外的例子。"}
    ]
  }'

Windows request body: text-generation-6.json

Save this JSON in the current directory as UTF-8 without BOM, replacing YOUR_... values with actual model IDs or other required values. JSON files do not expand environment variables: changing a terminal model variable does not change this file. Do not use Windows PowerShell 5.1 > to create it, because that defaults to UTF-16LE. Both Windows commands below read the same file. Microsoft: character encoding

{
  "model": "YOUR_MESSAGES_MODEL_ID",
  "max_tokens": 512,
  "messages": [
    {
      "role": "user",
      "content": "请解释幂等请求，并举一个支付接口之外的例子。"
    }
  ]
}

Windows — PowerShell

curl.exe --fail-with-body --silent --show-error "${env:AIONROUTER_BASE_URL}/v1/messages" -H "x-api-key: ${env:AIONROUTER_API_KEY}" -H 'anthropic-version: 2023-06-01' -H 'Content-Type: application/json' --data-binary '@text-generation-6.json'

Windows — CMD

curl.exe --fail-with-body --silent --show-error "%AIONROUTER_BASE_URL%/v1/messages" -H "x-api-key: %AIONROUTER_API_KEY%" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" --data-binary "@text-generation-6.json"

Output is in the content block array; text blocks have type text. Use the protocol's top-level system field for system instructions, rather than copying the entire Chat Completions body.

Accumulate complete streaming events. A network read can contain half a UTF-8 character, part of a JSON value or several events. Decode characters and frame events before parsing the protocol. Display confirmed text deltas if appropriate, but do not execute incomplete tool arguments.

Complete the tool-call loop. Check that the requested tool is allowed and its arguments are valid, execute it, then return the result with the matching call ID using the original protocol. Request the model's final answer afterward. Apply your own authorization and confirmation rules to writes and external actions.

Test the particular Responses interaction you need. Basic text, tool events, context compaction and client extensions may follow different paths. For coding clients, test actual client requests; one successful /v1/responses text call does not establish compatibility with every agent feature.

Move from command-line testing to an application

Terminal examples verify requests. For websites and mobile apps, keep the API key on your backend and pass permitted results to the frontend. Do not compile a full platform key into web scripts.

Integrate a call into a business task in this order:

1. Assign your own task ID and record the model, endpoint and necessary input summary.
2. Validate user access, task size and concurrency on your server instead of passing arbitrary models and parameters through.
3. Set suitable waits for the request, first streaming event and complete response separately.
4. Handle successful text, tool calls, empty results, truncation and errors separately.
5. Record available request IDs and usage. Treat client timeouts or interrupted streams as uncertain outcomes, not zero usage.
6. Compare models and parameters using the same anonymized samples; check correctness, latency and actual usage before expanding.

Model text such as “I sent it” or “I checked it” does not prove an operation happened. Rely on your tool execution results and business data.

Handle errors, rate limits and usage reconciliation

Errors and cost checks

• Invalid parameters: verify a minimal request, then add reasoning, structured-output or tool settings one at a time.
• Unavailable model: check the full ID, key restrictions, group and endpoint.
• Rate limits: reduce concurrency and use bounded backoff for retryable requests.
• Stalled streams: check buffering and idle timeouts along the client, reverse proxy and gateway path.
• Truncation: inspect the finish reason and model output limit; do not treat incomplete content as a complete business result.

Check model details and pricing and console usage records for actual charges. Models can price input, output, cache and other dimensions differently; usage.total_tokens is not necessarily the entire charge multiplied by one unit price.

Retain time, model ID, endpoint, error body and X-Oneapi-Request-Id for troubleshooting, but never the complete key.

429 is not only about concurrent requests. Request frequency and token throughput are distinct. Long histories, large output limits and multiple candidates can increase request size. Respect Retry-After and bound total retries across the SDK and application.

Distinguish business rejection from HTTP failure. A response failing your field validation does not mean the upstream model never generated it. Regeneration is a new call and may consume additional usage; make that clear to your users.

Reassess costs when changing models. Input, output, caching and other charges may differ. Client estimates may use outdated settings. Reconcile against current prices visible to your account and actual usage records; this guide supplies no universal price or inferred discount amount.

FAQ and related guides

Frequently asked questions

What changes when connecting an OpenAI application?

Start with the service URL, API Key and model ID, then check API and parameter compatibility. If the SDK's base_url needs an API prefix, it normally ends in /v1; do not use the full /chat/completions endpoint as the base.

Are Chat Completions, Responses and Messages interchangeable?

Both the request and response handling must change. They are different JSON protocols, so changing a path without updating its body can fail.

Why does the model forget the previous conversation?

Check that the application sends the required history or correctly uses a supported conversation-reference mechanism. Sending only the next question does not automatically include past application messages.

Why can a model chat but fail in a coding Agent?

Agents may also require tools, streaming events, long context or specific Responses/Messages behavior. One successful text answer verifies only that basic call, not the entire Agent feature set.

Does temperature 0 guarantee identical output? Do not assume so. Record the model version, input, supported parameters and tool results, and build regression samples. Use business rules and validation when conclusions must be fixed.

Will a model read a URL or filename automatically? An address in text does not prove its content was read. The model, endpoint or application tool must explicitly support that input, and you must confirm the content was supplied.

Related guides

• API authentication and key management
• Client integration tutorial
• Image generation API
• Video generation API
• Text-to-speech API