Aimodra API reference
and integration guide.

Aimodra API base URL and auth

Use the Aimodra JSON API at https://api.aimodra.com. Requests use your four-hour and weekly allowance, drawn down at each model’s published input and output rate, including provider-reported cached input.

Get your API key

Create a key in API keys. Copy it when it is created; the full secret is shown only once. Keys start with aim_.

Authorization: Bearer YOUR_API_KEY

Keep the key on your application’s server. Revoking a key blocks subsequent requests made with it.

Connect coding clients to your API key

Connect Claude Code or Codex CLI to Aimodra in three steps. Both use your Aimodra allowance and model catalog.

1. Create an account, then check your plan and allowance. If using the trial, complete Telegram verification in your dashboard.
2. Create an API key. Copy it when shown and keep it private. Replace YOUR_AIMODRA_KEY in the examples with this key.
3. Choose a configured model below. A model must have a provider route compatible with your client.

The examples configure your coding client. Your Aimodra login password, ChatGPT subscription, and Claude subscription are not API keys. Never put a key in a shared repository.

Connect Claude Code

Install Claude Code using its official installation guide. Open a terminal in your project and check claude --version.

Set the connection and launch

Claude uses the base address without /v1. These variables apply to the current terminal session; start Claude from that terminal. Use /status to confirm the gateway and credential.

Confirm it works

Ask “Reply with hello.” Then check request logs and usage in Aimodra. A successful request should appear under the model you selected.

Reference: Claude Code gateway configuration.

Connect Codex CLI

Follow the official Codex CLI installation guide, then check codex --version.

Add a custom provider

In your user-level ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml), merge this provider block. If model_providers.aimodra exists, update it instead of adding it twice. Keep your other settings.

Set your key and launch

This launch selects Aimodra for the current run while preserving your default provider. The base URL includes /v1, and the wire API is responses.

Ask “Reply with hello.” Confirm the model in the CLI and look for the request in Aimodra logs. Set the key again in each new terminal, or provide it through your own secret manager.

Reference: OpenAI custom provider configuration.

Connection troubleshooting

401 / invalid key

Use an active Aimodra key and restart the client from the configured terminal. Revoke and replace an exposed key.

404 / wrong endpoint

Claude base URL has no /v1; Codex base URL ends with /v1. Neither uses /api/chat.

Unknown or unavailable model

Copy an exact configured ID from the catalog. Configured means listed, not guaranteed healthy or compatible with every protocol. Check with support if its native route is unavailable.

429 / allowance or request reservation

Check trial verification, plan expiry, and available allowance in the dashboard. A request may need a temporary reservation larger than the available funds even when confirmed spending is low. Check the required and available amounts in the error; reduce conversation size or the requested output limit. Rejected budget checks are not charged.

Client still uses another account

Launch from the same terminal. In Claude, remove conflicting gateway credential settings and inspect /status. In Codex, include the provider override shown above. Organization-managed settings may restrict custom providers.

Images or compaction fail

Vision requires a working native or assisted route. Remote Responses compaction depends on the provider; the previously tested route did not support it. Do not assume every client feature is available.

For support, include the client version, model, time, and request ID. Leave out API keys and private project content.

Make your first Aimodra request

Replace the key and model ID with values from your Aimodra dashboard, then inspect the request in your logs.

curl https://api.aimodra.com/api/chat \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Hello!"}]}'

A successful response includes message, model, requestId, and usage with input, output, and total tokens. Review actual requests in Logs.

AI model catalog and token pricing

One catalog, one API. Use the exact model ID in your request. Configured models have an enabled provider; this is not a live health guarantee. Planned models become available after a provider is connected.

For example, 300,000 input tokens plus 500,000 output tokens on claude-opus-5 costs $0.48 + $2.00 = $2.48. Your plan’s dollar price and four-hour and weekly limits remain unchanged. Planned models cannot be requested or billed yet. A configured model with no published rate bills at $1.666667 per million each way until its rate is listed.

Read the current catalog from GET /api/models. This public endpoint returns configured model IDs and each model’s tier and per-million input and output rate, without provider details.

When multiple providers offer the same model, Aimodra tries another matching provider if the first cannot answer. Customer usage is charged once for the successful response.

The request contract

model

Required. An enabled model ID.

messages

Required. 1–30 user/assistant messages, ending with a user message. Each message contains role and content. A single message may be as large as the request body allows.

provider

Optional preferred provider ID, configured by your administrator.

Limits

8 MB request body, up to 8,192 output tokens (2,048 by default), 60 requests per minute, and 8 concurrent requests per account. Rate limits are the same on every plan; a paid plan raises your spending allowance, not your request rate.

SDK-compatible endpoints

Use POST /v1/messages for Anthropic Messages, POST /v1/responses for Responses, or POST /v1/chat/completions for OpenAI-style text requests. These endpoints use your Aimodra API key and the same allowance, model routing and billing. GET /v1/models lists configured models.

Authentication: send Authorization: Bearer YOUR_API_KEY or x-api-key: YOUR_API_KEY. For the OpenAI SDK, set base_url to https://api.aimodra.com/v1. For the Anthropic SDK, set base_url to https://api.aimodra.com.

Set stream: true to receive text as the provider generates it. Failover is possible before the first text chunk; once output starts, a failed stream ends with an error rather than switching models or replaying text. Usage is finalized after the provider supplies its usage totals. Interrupted requests may retain a reservation for review.

Images & assisted vision

Attach images in dashboard chat, send Anthropic image blocks to /v1/messages, or send input_image blocks to /v1/responses. Use JPEG, PNG, WebP or GIF. A working vision route must be available.

Verified native routes receive the original image. For other models, an available verified vision model can describe the image first; your selected model then answers using that description. This is assisted vision: fine visual details and precise coordinates may be lost. Up to eight images can be analyzed in one assisted request. If no verified helper exists, images are passed to the selected native route without a claim that it supports vision.

Image descriptions remain within the request and are reused during failover. The service covers the helper model’s processing cost; the selected model’s reported usage, including the description as input, counts toward your allowance. Token-counting requests never trigger paid image analysis.

Understand the response

400

Invalid JSON, model, or message format.

401

Missing, invalid, or revoked API key.

429

Rate limit, provider quota, or available allowance reached.

503

Aimodra is temporarily unavailable. The error includes the API base URL, never an upstream provider URL.

504

The provider did not finish within 90 seconds.

Error responses contain an error.message. Unknown provider usage may retain its reservation for review.

Before generation, Aimodra reserves an estimate for input plus the maximum requested output at the selected model’s published rates. This temporary reservation is not the final charge. Reported usage settles the cost and releases unused funds. Confirmed spending and pending reservations appear separately in your dashboard. If a single request needs more than your entire four-hour limit, waiting for that limit to reset will not make the same request fit; use a smaller request or contact support if the estimate looks incorrect. Do not repeatedly retry an unchanged budget rejection.