API documentation

Huru is an OpenAI-compatible REST API powered by 0G decentralized compute. Every response is TEE-verified. Billing is prepaid credits — charge your project, or pass costs to your end-users with one header.

Quickstart

Grab your API key from the dashboard and make your first call.

Your first requestcurl

curl https://huruai.xyz/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "huru/chat-1",
    "messages": [
      { "role": "user", "content": "Hello from Huru" }
    ]
  }'

200Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [{
    "message": { "role": "assistant", "content": "Hello! ..." },
    "finish_reason": "stop"
  }],
  "huru": {
    "request_id": "req_8f3a2b1c4d5e6f",
    "credits_used": 1,
    "verified": true,
    "verification_mode": "tee",
    "provider": "0g"
  }
}

Tip: Every response includes a huru object with your request ID, credits consumed, and TEE verification status.

Authentication

Every request requires a project API key as a Bearer token. Keys start with sk_test_ (test) or sk_live_ (live).

Authorization: Bearer sk_test_abc123...

Important: Never expose your API key in client-side code. If compromised, rotate it from the dashboard immediately.

Models

Model	Type	Description
huru/chat-1	Chat	General-purpose chat completions
huru/stt-1	Speech-to-text	Audio transcription via multipart upload

Huru routes to the best available 0G provider automatically with up to 3 failover attempts.

Credits

API requests cost credits. Credits are reserved before the request and settled after. Failed requests refund automatically. ~1 credit per 1,000 tokens (chat) or ~1 per 500 KB audio.

Starter Top-Up

100credits

10 NGN

Builder Top-Up

300credits

25 NGN

Pilot Top-Up

1400credits

100 NGN

Consumer billing

Let your end-users pay for their own compute. Add one header and Huru handles identity, credit accounts, metering, and payment. You spend $0.

Send the header

Add X-Consumer-Email to any request. Optionally include X-Consumer-Name.

Auto-provision

First time? Huru creates the consumer and awards 10 starter credits.

Deduct from consumer

Credits reserved and settled against the consumer’s balance, not yours.

Self-serve top-up

At zero credits, the 402 response includes a checkout_url pre-filled with their email.

Headers

X-Consumer-Emailstringrequired

End-user's email. Must contain @. Identifies the consumer within your project.

X-Consumer-Namestring

Display name. Shown on Paystack checkout. Optional.

Request with consumer billingcurl

curl https://huruai.xyz/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Consumer-Email: jane@example.com" \
  -H "X-Consumer-Name: Jane Doe" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "huru/chat-1",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

When a consumer runs out of credits, you get a 402 with a checkout link:

402Response

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "Consumer does not have enough credits.",
    "checkout_url": "https://paystack.com/pay/..."
  }
}

Note: Omit the header and billing falls back to your project balance. 100% backward compatible.

API reference

All endpoints live under https://huruai.xyz.

POST/v1/chat/completions

Generate a chat completion. OpenAI-compatible. Supports streaming.

modelstringrequired

Must be huru/chat-1.

messagesarrayrequired

Array of { role, content } objects.

streamboolean

Set to true for SSE streaming. Default false.

Examplecurl

curl https://huruai.xyz/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "huru/chat-1",
    "messages": [
      { "role": "system", "content": "You are helpful." },
      { "role": "user", "content": "Explain TEE in one sentence." }
    ]
  }'

POST/v1/audio/transcriptions

Transcribe audio to text. Accepts multipart form data.

fileFilerequired

Audio file (mp3, wav, m4a, webm).

modelstringrequired

Must be huru/stt-1.

Examplecurl

curl https://huruai.xyz/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F file=@recording.mp3 \
  -F model=huru/stt-1

GET/v1/consumers

List all consumers under the authenticated project with balances.

200Response

{
  "object": "list",
  "data": [
    {
      "id": "con_abc123",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "credits_balance": 42,
      "created_at": "2026-04-27T15:30:00Z"
    }
  ]
}

GET/v1/consumers/:consumerId

Get a single consumer's detail and credit balance.

POST/v1/consumers/:consumerId/checkout

Create a Paystack checkout pre-filled with the consumer's email.

pack_idstringrequired

One of credits_10, credits_25, credits_100.

Examplecurl

curl -X POST https://huruai.xyz/v1/consumers/con_abc123/checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pack_id": "credits_10" }'

201Response

{
  "object": "checkout.session",
  "provider": "paystack",
  "reference": "huru_topup_a1b2c3d4e5f6",
  "authorization_url": "https://paystack.com/pay/...",
  "credits_awarded": 100,
  "status": "pending"
}

GET/v1/usage

Usage totals and daily breakdown. Optional from and to query params (ISO 8601).

Examplecurl

curl "https://huruai.xyz/v1/usage?from=2026-04-01&to=2026-04-27" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/requests/:id

Retrieve a request record with status, usage, and errors.

GET/v1/requests/:id/verification

Get the TEE attestation report for a request. Includes report ID, quote hash, and verification timestamp.

200Response

{
  "verified": true,
  "verification_mode": "tee",
  "provider": "0g",
  "report_id": "att_...",
  "quote_hash": "0xabc123...",
  "verified_at": "2026-04-27T15:30:00Z"
}

POST/v1/billing/checkout

Start a Paystack checkout for project-level credits. For consumer top-ups use /v1/consumers/:id/checkout.

pack_idstringrequired

Credit pack ID.

success_urlstring

Redirect after payment.

cancel_urlstring

Redirect on cancel.

POST/v1/projects

Create a project and get your API key + starter credits.

namestringrequired

Project display name.

slugstring

URL-safe ID. Auto-generated if omitted.

environmentstring

test or live. Default: test.

Idempotency

Pass an Idempotency-Key header to safely retry requests without double-charging.

Idempotent requestcurl

curl https://huruai.xyz/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{ "model": "huru/chat-1", "messages": [...] }'

Completed — returns cached response with idempotent_replay: true.

Processing — returns 409. Wait and retry.

Failed — allows a new attempt.

Streaming

Set stream: true on chat completions for server-sent events. The stream opens and closes with Huru metadata events.

Stream formattext

data: {"huru":{"request_id":"req_abc123"}}

data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{"content":" world"}}]}

data: {"huru":{"request_id":"req_abc123","credits_used":1,"verified":true}}

data: [DONE]

Note: Consumer billing works with streaming. Credits are reserved before the stream, settled on completion, released on disconnect.

Rate limits

Token-bucket rate limiter per project.

Window	Limit	Header
Per minute	60	X-RateLimit-Limit-Minute
Per day	1000	X-RateLimit-Limit-Day

When limited, you get 429 with X-RateLimit-* headers showing remaining quota and reset time.

Errors

All errors return a consistent shape. Consumer billing errors include checkout_url.

Status	Code	Description
400	invalid_request	Bad body, missing field, or unsupported model.
401	authentication_error	Missing or invalid API key.
402	insufficient_credits	Not enough credits. Consumer 402s include checkout_url.
409	request_in_progress	Idempotent request already processing.
429	rate_limit_exceeded	Rate limit hit. Check X-RateLimit-* headers.
503	provider_unavailable	0G provider temporarily down.

Error shapejson

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "Consumer does not have enough credits.",
    "checkout_url": "https://paystack.com/pay/..."
  }
}

Built on 0G decentralized compute. Every response is TEE-verified.