Skip to main content

Documentation Index

Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
CLI First

# Check usage and buy more credits
naive usage --days 30
naive billing packs
naive billing topup --pack medium

​
How Credits Work

Every company has a credit balance. Operations deduct credits on use. New accounts start with 100 free credits.

​
Credit Costs

Each credit is worth $0.50 USD.

​
Fixed-Price Operations

OperationCreditsCharging
Email send1Immediately on success
Web search1Immediately on success
URL read1Immediately on success
Research (quick)3Immediately on success
Research (thorough)5On job completion
Research (exhaustive)8On job completion
Stock photo search0Free

​
Dynamic-Price Operations (Image/Video Generation)

Image and video generation costs are model-dependent and calculated dynamically:
Formula
Costmodel unit price × quantity
Creditscost ÷ $0.50 (rounded up)
Use the pricing endpoints to preview costs before submitting: 
GET /v1/images/pricing?model=fal-ai/flux/schnell&num_images=2
GET /v1/video/pricing?model=fal-ai/kling-video/v3/pro/text-to-video&duration=5
Response: 
{
  "model": "fal-ai/flux/schnell",
  "estimated_credits": 0.12,
  "fal_unit_price_usd": 0.02,
  "credit_value_usd": 0.50
}

​
Sync vs Async Charging

Synchronous operations (email, search, URL read, quick research):
  • Credits deducted immediately when the operation succeeds
  • If it fails, no credits are charged
Asynchronous operations (images, video, thorough research):
  1. On submission: pre-check that balance ≥ estimated cost (returns 402 if not)
  2. Job runs in background
  3. On success: credits deducted and transaction recorded
  4. On failure: no charge
Concurrent async jobs can temporarily exceed your balance since pre-checks pass independently. The balance may go slightly negative — subsequent submissions will be blocked once balance drops below threshold.

​
Checking Your Balance

GET /v1/status
Returns your current balance, tier, and resource counts.

​
Usage History

GET /v1/usage?days=30&limit=50
Returns transaction history with action type, amount, and reference IDs.

​
Credit Responses

Every operation that costs credits includes the charge in its response: 
{
  "credits_used": 1,
  "credits_remaining": 99
}
For async jobs, the estimated cost is shown on submission: 
{
  "job_id": "uuid",
  "estimated_credits": 2,
  "hint": "Credits charged on completion only."
}

​
Running Low on Credits?

When your balance hits zero, operations fail with an insufficient_credits error that includes available credit packs. You can buy more anytime: 
# See available packs
naive billing packs

# Buy credits
naive billing topup --pack medium   # 50 credits for $23
Or upgrade your plan for more monthly credits: 
naive billing upgrade --plan pro    # 200 credits/mo
See Billing & Credits for full details on plans and pricing.