Call Athena from your own apps

Athena is a model in the aixplain Marketplace, so you can call it from anywhere with an aixplain API key: your own app, a script, another AI framework or an MCP client. This article explains how to get a key and call Athena through the OpenAI-compatible API and through MCP.

What you need

• An aixplain API key: create one in the aixplain app under Settings → API keys. The full key is shown only once, so copy it then.
• Athena's model name: aixplain/llm-router/aixplain. Its Marketplace ID, 6ab559cabbbd3609ac7e86cf, works too.

Call Athena through the OpenAI-compatible API

Athena answers the OpenAI chat completions format at https://models.aixplain.com/api/v1. Any client, framework or tool that lets you set an OpenAI base URL can use it.

From a terminal:

curl https://models.aixplain.com/api/v1/chat/completions \
  -H "Authorization: Bearer $AIXPLAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aixplain/llm-router/aixplain",
    "messages": [{"role": "user", "content": "Why is my checkout test flaky?"}]
  }'

In Python, with the OpenAI client:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["AIXPLAIN_API_KEY"], base_url="https://models.aixplain.com/api/v1")

completion = client.chat.completions.create(
    model="aixplain/llm-router/aixplain",
    messages=[{"role": "user", "content": "Why is my checkout test flaky?"}],
)
print(completion.choices[0].message.content)

Athena supports streaming, tools, max_tokens, temperature, reasoning_effort and response_format, like other chat models.

See which model answered

Every response carries a router field with the tier Athena chose and the model that served the request. You're billed at that model's price.

router = completion.model_extra["router"]
print(router["servedTier"], router["model"]["name"])

servedTier is fat (Deep), slim (Standard) or fast (Quick).

Choose the tier yourself

To skip the classifier for a request, set router_tier to fat, slim or fast. With the OpenAI client, pass it as extra_body={"router_tier": "fast"}. Athena may still serve the request on a stronger tier, and router shows which one did.

Use Athena in other AI projects

Coding agents, chat apps and AI frameworks that accept a custom OpenAI-compatible provider can run on Athena. In the tool's settings:

1. Add a custom provider with the base URL https://models.aixplain.com/api/v1.
2. Enter your aixplain API key.
3. Set the model to aixplain/llm-router/aixplain.

Call Athena through MCP

Every model in the Marketplace is also a hosted MCP server, Athena included. Add it to any MCP client that connects to a URL, with your API key:

{
  "mcpServers": {
    "athena": {
      "url": "https://models-mcp.aixplain.com/mcp/aixplain%2Fllm-router%2Faixplain",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Clients that only run local commands can reach the same URL through the mcp-remote bridge. For both setups and a connection test, see MCP servers in the Agents SDK docs.

Pricing and usage

Each request costs what the model that answered it costs, from your workspace's credits. Your workspace's usage page breaks usage down by API key, and you can cap a key's spending. See Your account, plans and billing.

Limitations

• To choose the models behind each tier, create your own router with Automode, then call it by its ID like any other model.
• Athena runs on aixplain on cloud. For routing on your own servers, ask us at care@aixplain.com.

Troubleshooting

I get "err.not_enough_balance"

The workspace your key belongs to is out of credits. Top it up, then try again.

I get "Forbidden" or 401

The key is wrong, deleted or expired. Create a new key and try again.

Get help

• Build an agent on Athena: see Run your agents on Athena.
• API reference: see the Agents SDK docs.
• Report a problem: email care@aixplain.com with the request, the time and the error you got.