Conventions

The shared rules every capability follows over raw HTTP: the request envelope, response metadata, the wire contract and idempotency. No SDK required.

Request & response envelope

Every native infrai REST call is a POST (or GET) to https://api.infrai.cc/v1/… with a Bearer key and a JSON body. Native REST responses use the same envelope:

OpenAI-compatible AI inference endpoints, such as /v1/chat/completions and /v1/embeddings, intentionally keep the OpenAI response shape and add a top-level infrai metadata block instead of this envelope.

json

{
  "ok": true,
  "data": { /* capability-specific result */ },
  "error": null,
  "metadata": {
    "cost_usd": 0.00012,
    "latency_ms": 412,
    "vendor": "deepseek",
    "cache_hit": false,
    "request_id": "01HXY..."   // UUID v7
  }
}

Result metadata

Every call returns its data plus a metadata block, so an agent can read cost and latency without a vendor round-trip.

cost_usd · USD cost of this call, reconcilable with your bill.
latency_ms · End-to-end latency in milliseconds.
vendor · The upstream vendor that served the call.
cache_hit · Whether the response was served from cache.
request_id · Globally unique id (UUID v7) for support and reconciliation.

Wire contract

Call the API directly from any language over HTTPS. The shared wire rules:

Authentication	`Authorization: Bearer <infrai_project_key>`
Request body	Canonical JSON: sorted keys, no spaces, trailing newline, UTF-8.
Idempotency header	`Idempotency-Key`
Request id	`metadata.request_id (UUID v7)`

Idempotency

Idempotency keeps retries safe — the same key never double-charges or duplicates a resource within the dedup window.

Read (GET) calls are idempotent by default — no key needed.
Cost-incurring calls derive a key server-side; passing your own is recommended.
Resource-creation calls should send an idempotency key for safe retries; current public APIs no longer require callers to provide one.

bash

# Cost-incurring calls: send an Idempotency-Key header so retries never double-charge.
curl -X POST https://api.infrai.cc/v1/email/send \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirmed-123" \
  -d '{"to": "customer@x.com", "subject": "Order #123 confirmed", "html": "<p>Thanks!</p>"}'

When you omit a key on a cost-incurring call, the server derives one deterministically:

text

idempotency_key = sha256(account_id + request_id + capability + content_hash)

The default dedup window is 24 hours (minimum 1 hour, maximum 7 days). A repeat within the window returns the original result without re-charging.