# Clervo API quickstart

The current callable beta models use free or sponsored launch funding by default. No wallet or payment header is required for this flow.

```bash
export CLERVO_API_URL=https://api.clervo.dev

# 1. Discover models. Use only entries where callable is true.
curl -sS "$CLERVO_API_URL/v1/models"

# 2. Make an idempotent OpenAI-compatible chat call and save response headers.
curl -sS -D /tmp/clervo-headers -o /tmp/clervo-response.json "$CLERVO_API_URL/v1/chat/completions"   -H 'content-type: application/json'   -H 'idempotency-key: quickstart-call-0001'   -d '{"model":"clervo/fast","messages":[{"role":"user","content":"Say hello in five words."}],"max_completion_tokens":64}'
cat /tmp/clervo-response.json

# 3. Read the durable operation ID and look up customer-safe status/receipt metadata.
OPERATION_ID="$(awk 'BEGIN { IGNORECASE=1 } /^x-clervo-operation-id:/ { gsub("\r", "", $2); print $2 }' /tmp/clervo-headers)"
test -n "$OPERATION_ID"
curl -sS "$CLERVO_API_URL/v1/operations/$OPERATION_ID"

# 4. Re-run step 2 with the same idempotency key and identical body to replay safely.
```

The response header `x-idempotent-replay` is `true` on a completed replay. Reusing an idempotency key with a different body returns a conflict.

## Paid x402 launch offer

Callable models may also publish `paid_pricing`. To request the x402 payment challenge instead of using free or sponsored funding, repeat the same request with:

```bash
curl -sS -D - "$CLERVO_API_URL/v1/chat/completions"   -H 'content-type: application/json'   -H 'x-clervo-funding: paid'   -d '{"model":"clervo/fast","messages":[{"role":"user","content":"Say hello in five words."}],"max_completion_tokens":64}'
```

The response is HTTP 402 with a standard `PAYMENT-REQUIRED` header. Submit the wallet-produced `PAYMENT-SIGNATURE` header with the same request body to execute the paid call.

QuickAI-prefixed model IDs are provider-observed labels, not independently verified upstream provenance claims.