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://www.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.

Sip

50credits

100 NGN

Sample

100credits

200 NGN

Starter

1000credits

2,800 NGN

Pro

5000credits

12,600 NGN

Business

25000credits

49,000 NGN

Scale

100000credits

138,600 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 200 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://www.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://www.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://www.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://www.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 pack_starter, pack_pro, pack_business, pack_scale.

Examplecurl

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

201Response

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

GET/v1/usage

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

Examplecurl

curl "https://www.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://www.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.