API documentation

Quickstart

1. 1Create an air_ key in Dashboard → API keys.
2. 2Open the Marketplace, choose a provider offer, and enable PAYG.
3. 3Copy that offer's Air model ID.
4. 4Add Air Credits.
5. 5Call POST /chat/completions with that model ID.

curl https://www.airinference.com/api/v1/chat/completions \
  -H "Authorization: Bearer $AIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "air_gpt4o_pa_7K4D",
    "messages": [{"role": "user", "content": "Hello from Air"}]
  }'

Air model IDs

Each Air model ID maps to exactly one provider offer (one provider + one upstream model). Air does not automatically switch providers.

Air model ID
      ↓
exact provider offer
      ↓
provider model ID
      ↓
provider endpoint

air_gpt4o_pa_7K4D
→ Provider A
→ upstream model: gpt-4o

Get an ID: Marketplace → choose offer → Enable PAYG → Copy Air model ID.

Air model IDs are provider-specific and immutable. To use another provider for the same underlying model, enable that provider's separate Air model ID and send another request.

Authentication

Authorization: Bearer air_...

Create keys in Dashboard → API keys. Keep the key server-side — do not expose it in browser or client-side code.

Base URL

https://www.airinference.com/api/v1

Use this as baseURL / base_url with the OpenAI SDK. Paths below are relative to this base (API version /v1).

Streaming

Set stream: true. Air proxies text/event-stream from the provider. Air requests stream_options.include_usage so token usage can be metered after the stream ends; Credits are finalized from that usage (reserve → capture).

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AIR_API_KEY,
  baseURL: "https://www.airinference.com/api/v1",
});

const stream = await client.chat.completions.create({
  model: "air_gpt4o_pa_7K4D",
  messages: [{ role: "user", content: "Say hello" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

If the offer does not support streaming, the API returns 400 capability_unsupported.

Enable a model

Marketplace
→ choose provider / model offer
→ Enable PAYG
→ copy Air model ID

Enabling one provider's model does not enable another provider's model, even when both offer the same underlying model.

air_gpt4o_pa_7K4D
does not enable
air_gpt4o_pb_92QF

If you enable both, choose which Air model ID to send per request. Air does not automatically pick between them or fail over.

Billing

PAYG uses Air Credits. Each chat request reserves an estimate, calls the provider, then charges actual usage and releases the unused hold.

Air Credits
→ temporary reservation
→ provider request
→ actual usage
→ final charge
→ unused reservation released

Reservations are temporary holds, not additional charges. Final billing uses measured tokens.

Reserved: $0.001625
Actual:   $0.000029
Released: $0.001596
Final charge: $0.000029

Pricing

Cost is computed from the offer's rate card (USD per 1M tokens). There is no cent-rounding floor on the charge — amounts use high-precision USD.

cost =
  prompt_tokens × input_usd_per_1m / 1,000,000
+ completion_tokens × output_usd_per_1m / 1,000,000

Historical usage keeps the rate card that applied at call time. New calls use the current active rate.

Wallet

GET /me/wallet returns available / reserved Credits. Top up in the dashboard. Optional per-account spending limits are enforced when configured. Auto-recharge may run after successful calls when enabled for your account.

curl https://www.airinference.com/api/v1/me/wallet \
  -H "Authorization: Bearer $AIR_API_KEY"

Errors

Errors use an error object. Important codes for /chat/completions:

{
  "error": {
    "message": "Model is not enabled for this account. Enable it on the marketplace listing page.",
    "code": "model_not_enabled",
    "model": "air_gpt4o_pa_7K4D",
    "marketplace": "https://www.airinference.com/dashboard/marketplace"
  }
}

{
  "error": {
    "message": "Insufficient Air Credits. Top up to continue.",
    "type": "insufficient_quota",
    "code": "insufficient_credits",
    "model": "air_gpt4o_pa_7K4D"
  },
  "air": {
    "available": "0.12",
    "reserved": "0",
    "topup": "https://www.airinference.com/dashboard/credits"
  }
}

Idempotency

Optional on POST /chat/completions:

Idempotency-Key: <unique-request-key>

• Same key + same request body → safe replay of the stored response.
• Same key + different body → 409 idempotency_conflict.

Rate limits

60 requests / minute / API key across authenticated /api/v1 routes. When exceeded, the API returns 429 with a Retry-After header (seconds).

OpenAI SDK

Air provides an OpenAI-compatible API. Use the standard OpenAI SDK with Air's base URL and an Air model ID. Air supports the fields and behavior documented on this page — not every OpenAI product feature.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AIR_API_KEY,
  baseURL: "https://www.airinference.com/api/v1",
});

const response = await client.chat.completions.create({
  model: "air_gpt4o_pa_7K4D",
  messages: [{ role: "user", content: "Hello from Air" }],
});

console.log(response.choices[0].message.content);

Providers

Publish a PAYG offer from the dashboard:

Provider
→ create listing / model offer
→ enter provider model ID + PAYG rates
→ Base URL + upstream API key
→ Validate
→ set Live

Validation checks the endpoint, credentials, model availability, a small inference request, and response shape. After publication, Air monitors offer health. If that exact provider is unavailable, the API returns an error — Air does not silently switch providers.

API version

These docs describe the /api/v1 API. Paths such as /chat/completions are relative to https://www.airinference.com/api/v1.