API reference

Base URL

https://api.amanai.dev/v1

The API is HTTPS-only. Use dedicated modality guides for request fields and examples; this page defines the behavior shared by every endpoint.

Authentication

Pass an Amanai API key as a Bearer token. Anthropic-compatible clients may use x-api-key where the SDK expects it.

Authorization: Bearer sk-amanai-...
# Anthropic-compatible alternative
x-api-key: sk-amanai-...

Keys can carry model scopes, budgets, rate limits, and expiry. Treat them as secrets and never expose them in browser code, logs, filenames, or query strings.

Endpoint directory

Common headers

Discovery and source of truth

Use authenticated discovery whenever a client exposes model selectors:

GET /v1/models
GET /v1/models?type=embedding
GET /v1/models?type=rerank

System One uses model amanai/jev-1.13 and its own native request format; do not send it to a chat endpoint.

The catalog is key-aware. A model absent from the response must not be offered to that key. Use GET /calculate/models and GET /calculate for quoting; use Billing & pricing for the public explanation of each unit.

Async operations and ownership

• Chat and image operations normally return synchronously or stream on the same connection.
• Video uses a durable job: submit, poll the returned ID, then use the completed artifact URL.
• Realtime keeps one session across multiple turns and requires explicit cleanup.
• Files, jobs, sessions, and artifact grants are bound to the authenticated owner.
• Generated artifact URLs can expire and should not be treated as permanent hosting.

Errors

For Chat Completions, Messages, Responses, and Messages token counting, errors use the codes below. Read error.code for programmatic handling; error.type follows the endpoint format. Messages errors also include type: "error". Requests that fail before usable delivery are not charged; partially delivered streaming usage can be settled.

Example: HTTP 503 temporary unavailability.

{
  "error": {
    "message": "The selected model is temporarily unavailable. Please try again shortly.",
    "type": "model_temporarily_unavailable",
    "code": "model_temporarily_unavailable"
  }
}

Specific message variants identify invalid JSON, a confirmed context limit, or a cybersecurity policy decision. They keep the same code and HTTP status as the corresponding row:

• request_blocked_by_policy: This request could not be processed because it was flagged for possible cybersecurity risk.
• request_too_large: The conversation exceeds the supported context limit. Shorten or compact it and try again.
• invalid_request_error: The request body is not valid JSON.

Other failures use model_temporarily_unavailable with the temporary-unavailability message above. Do not infer a specific cause from that code.

Streaming and buffered responses

HTTP status describes an error only before response headers are sent. A response that has already started can retain HTTP 200 and later contain an error. Chat Completions sends a data: error object; Messages sends event: error; Responses sends event: response.failed with response.error.code and response.error.message. A buffered JSON response can also finish with an error body after initial whitespace. Always inspect the body and terminal event rather than HTTP status alone.

Partial text or tool arguments are incomplete when a stream fails. Do not execute an incomplete tool call. Before retrying an action, check whether it already ran to avoid duplicates.

Retrying and support

Correct request, authentication, permission, credit, context, and policy errors before retrying. For temporary failures, use bounded retries with exponential backoff and jitter. Honor a numeric Retry-After header when present. Do not retry repeatedly without a delay.

Save the X-Amanai-Request-ID response header when contacting support. Messages responses also expose request-id and errors include request_id. A valid caller-supplied X-Request-ID is echoed separately. Include the public model, endpoint, approximate time, and request ID; never share your API key.

Other API families, including durable media jobs, can use endpoint-specific codes documented on their own pages.