// quickstart

Quickstart

Five minutes from zero to a streaming chat completion through the Aetherin API. All routes live under https://api.aetherin.app/v1.

1

Get an API key

Sign in to the API Keys page and create a key. The plaintext key is shown once — store it in your secret manager. Keys are scoped to a workspace and carry a monthly budget and an RPM limit.
2

List models

Fetch the OpenAI-compatible model list with your key. Response shape: { "data": [...], "has_more": false }.
curl -sS "https://api.aetherin.app/v1/models" \
  -H "Authorization: Bearer $AETHERIN_KEY"
3

Call chat completions

Use model dolphin-3-8b. Non-streaming request:
curl -sS "https://api.aetherin.app/v1/chat/completions" \
  -H "Authorization: Bearer $AETHERIN_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "model": "dolphin-3-8b",
    "messages": [{"role":"user","content":"Hello!"}]
  }'
4

Stream with SSE

Add "stream": true and use curl -N so output is not buffered.
curl -sN "https://api.aetherin.app/v1/chat/completions" \
  -H "Authorization: Bearer $AETHERIN_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "model": "dolphin-3-8b",
    "messages": [{"role":"user","content":"Hello!"}],
    "stream": true
  }'
5

Try the playground

Prefer a UI? Open the playground at https://aetherin.app/playground to chat with models interactively before wiring up your own client.

Budgets, limits and errors

  • Budget — when the key/workspace budget is exhausted the API returns 402 with code budget_exceeded. Budgets roll over monthly.
  • Rate limit — exceeding the key's rpm_limit returns 429 with code rate_limit_exceeded.
  • Errors — every failure uses the same envelope:
{
  "error": {
    "code": "budget_exceeded",
    "message": "monthly budget exhausted",
    "type": "payment_required",
    "param": null,
    "request_id": "req_01HXYZ"
  }
}

Branch on error.code, never on message. Quote request_id in support requests. See Error Codes for the full table.

Pagination

List endpoints take limit (1–200, default 50) and an opaque cursor. Stop when has_more is false.

curl -sS "https://api.aetherin.app/v1/keys?limit=50" -b cookies.txt
# → { "data": [...], "next_cursor": "key_01HXYZ", "has_more": true }

curl -sS "https://api.aetherin.app/v1/keys?limit=50&cursor=key_01HXYZ" -b cookies.txt