Developer API v0.1 preview

1. Authentication

Every request is authenticated with a bearer token:

Authorization: Bearer amai_live_<secret>

Create a key

1. Sign in at amaimedia.com/account.
2. Open Account → API keys.
3. Click Create key, give it a name, and copy the secret.

Revoke a key

Open the same page and click Revoke. Revocation takes effect on the next request — active requests are not interrupted.

2. Core endpoints v0.1 preview

Two runtime endpoints cover the billing flow every tool goes through: check the price and available balance, then spend when the work actually happens. Both are JSON in, JSON out.

POST/api/v1/tools/check

Quote a token cost against the caller's current balance. Idempotent, does not charge.

POST https://api.amaimedia.com/api/v1/tools/check
Content-Type: application/json
Authorization: Bearer amai_live_...

{
  "tool":  "chat",
  "units": 1
}

Request

Response

{
  "ok": true,
  "allowed": true,
  "cost_tokens": 5,
  "balance_after": 9995
}

POST/api/v1/tools/spend

Charge the account. Call this after the tool successfully produced its output. The reference string is your idempotency key — resending the same (tool, reference) pair will not double-charge.

POST https://api.amaimedia.com/api/v1/tools/spend
Content-Type: application/json
Authorization: Bearer amai_live_...

{
  "tool":      "chat",
  "units":     1,
  "reference": "req_2026-07-03_abc123"
}

Response

{
  "ok": true,
  "charged": 5,
  "balance_after": 9990
}

3. Rate limits

Rate limits are enforced per authenticated identity, not per IP. The current production caps (subject to change; see the roadmap) are:

Tool endpoints (/tools/check, /tools/spend) are gated by your token balance rather than a request-rate cap during the preview. A per-key request cap will be introduced with the GA release — see the roadmap.

4. Errors

All errors return a JSON body with ok:false and a stable error string. HTTP status codes follow standard semantics.

401 auth_required

{ "ok": false, "error": "auth_required" }

Missing, malformed, or revoked bearer token.

402 insufficient_credits

{
  "ok": false,
  "error": "insufficient_credits",
  "cost_tokens": 5,
  "balance": 2
}

Top up at amaimedia.com/credits.

403 forbidden

{ "ok": false, "error": "forbidden" }

CSRF mismatch, region blocked (OFAC), or account suspended.

429 rate_limited

{ "ok": false, "error": "rate_limited" }

Back off and retry after the window resets (see §3).

5. cURL example — check + spend

KEY="amai_live_your_secret_here"

# 1. Quote the cost before doing the work.
curl -sS https://api.amaimedia.com/api/v1/tools/check \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"chat","units":1}'
# => {"ok":true,"allowed":true,"cost_tokens":5,"balance_after":9995}

# 2. Do the actual tool call in your app.

# 3. Charge, idempotent by reference.
curl -sS https://api.amaimedia.com/api/v1/tools/spend \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"chat","units":1,"reference":"req_2026-07-03_abc123"}'
# => {"ok":true,"charged":5,"balance_after":9990}

6. Status & roadmap

The runtime tool endpoints are marked v0.1 preview. Shapes are stable enough to build against, but a few pieces are still moving:

• Bearer-key auth on /tools/* is rolling out — during the preview these routes may also accept session-cookie auth from the dashboard.
• Per-key request-rate limits will be published with GA.
• Tool-specific unit definitions may be extended (batch dub, streaming chat, etc).

Track breaking changes on the public roadmap. Every change ships with a dated entry there before the API behavior changes.