Credits

Credits are the primary unit of platform consumption. This page covers how to check your balance, view transaction history, browse credit packages, create a Stripe payment intent for purchases, and configure auto-refill.

Base URL: https://api.ainative.studio

---

Get Credit Balance

GET /api/v1/credits/balance

Returns the current credit balance for the authenticated user. Balance is computed by summing usage across ai_usage_logs, api_usage_logs, chat_completion_usage, and credit_transactions.

Auth required.

curl https://api.ainative.studio/api/v1/credits/balance \
  -H "Authorization: Bearer <your_api_key>"

import httpx

resp = httpx.get(
    "https://api.ainative.studio/api/v1/credits/balance",
    headers={"Authorization": "Bearer <your_api_key>"},
)
balance = resp.json()
print(f"Remaining: {balance['remaining_credits']} / {balance['total_credits']}")

Response

{
  "total_credits": 50000,
  "used_credits": 12340.5,
  "remaining_credits": 37659.5,
  "plan": "pro",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "usage_percentage": 24.68
}

Field	Description
total_credits	Total credits available this period (plan allowance + purchased)
used_credits	Credits consumed since period_start
remaining_credits	total_credits - used_credits (floored at 0)
plan	Current plan tier (free, basic, pro, enterprise)
period_start	Start of current billing period
period_end	End of current billing period (null for free tier)
usage_percentage	Percentage of credits consumed

---

Transaction History

GET /api/v1/credits/transactions

Paginated history of credit usage events from ai_usage_logs.

Auth required.

Query parameters

Param	Type	Default	Description
skip	integer	0	Records to skip
limit	integer	50	Max records (1–50)

curl "https://api.ainative.studio/api/v1/credits/transactions?skip=0&limit=20" \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn-uuid",
        "type": "usage",
        "amount": -4.5,
        "description": "chat_completion using gpt-4o",
        "tokens_processed": 1500,
        "processing_time_ms": 823,
        "created_at": "2026-04-25T09:30:00Z",
        "session_id": "session-uuid"
      }
    ],
    "total": 843,
    "skip": 0,
    "limit": 20,
    "has_more": true
  }
}

Note: amount is negative for usage deductions.

---

Current Period Usage

GET /api/v1/credits/usage/current

Aggregated usage statistics for the current billing period, broken down by operation type and day.

Auth required.

curl https://api.ainative.studio/api/v1/credits/usage/current \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "success": true,
  "data": {
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z",
    "summary": {
      "total_requests": 1204,
      "total_credits_used": 12340.5,
      "total_tokens_processed": 4100000,
      "unique_sessions": 38,
      "active_days": 22
    },
    "by_operation_type": [
      {
        "operation_type": "chat_completion",
        "request_count": 980,
        "credits_used": 10200.0
      },
      {
        "operation_type": "embedding",
        "request_count": 224,
        "credits_used": 2140.5
      }
    ],
    "daily_usage": [
      {
        "date": "2026-04-25",
        "request_count": 54,
        "credits_used": 540.0
      }
    ]
  }
}

---

Credit Packages

GET /api/v1/credits/packages

List available credit packages that can be purchased. Packages are loaded from the credit_packages database table; the response below shows the fallback list returned when the database is unavailable.

Auth required.

curl https://api.ainative.studio/api/v1/credits/packages \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "success": true,
  "data": {
    "packages": [
      {
        "id": "credits_250",
        "name": "250 Credits",
        "credits": 250,
        "price": 10.00,
        "currency": "USD",
        "popular": false,
        "description": "Starter pack for light usage",
        "features": ["250 prompt credits", "Works with all AI models", "Never expires", "Instant activation"]
      },
      {
        "id": "credits_1000",
        "name": "1,000 Credits",
        "credits": 1000,
        "price": 40.00,
        "currency": "USD",
        "popular": true,
        "description": "Best value for regular users",
        "features": ["1,000 prompt credits", "Works with all AI models", "Never expires", "Instant activation", "Priority processing"]
      },
      {
        "id": "credits_5000",
        "name": "5,000 Credits",
        "credits": 5000,
        "price": 175.00,
        "currency": "USD",
        "popular": false,
        "description": "High-volume pack for power users",
        "features": ["5,000 prompt credits", "Works with all AI models", "Never expires", "Instant activation", "Priority processing"]
      }
    ]
  }
}

---

Create Payment Intent for Credits

POST /api/v1/credits/payment-intent

Create a Stripe Payment Intent for purchasing a credit package. Returns a client_secret your frontend uses with Stripe.js to complete payment. Credits are added after the webhook confirms payment success.

Auth required.

Request body

Field	Type	Required	Description
package_id	string	Yes	Package ID from GET /credits/packages
amount	number	Yes	Amount in USD (must be > 0)

curl -X POST https://api.ainative.studio/api/v1/credits/payment-intent \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"package_id": "credits_1000", "amount": 40.00}'

import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/credits/payment-intent",
    headers={"Authorization": "Bearer <your_api_key>"},
    json={"package_id": "credits_1000", "amount": 40.00},
)
data = resp.json()["data"]
client_secret = data["client_secret"]
# Pass client_secret to Stripe.js on the frontend

Response

{
  "success": true,
  "data": {
    "payment_intent_id": "pi_xxx",
    "client_secret": "pi_xxx_secret_yyy",
    "amount": 40.00,
    "currency": "USD",
    "package_id": "credits_1000"
  },
  "message": "Payment intent created successfully"
}

Note

POST /api/v1/credits/purchase is disabled (501 Not Implemented). Use the payment intent flow above instead.

---

Auto-Refill Settings

Auto-refill automatically triggers a credit purchase when your balance drops below a configured threshold.

Get Auto-Refill Settings

GET /api/v1/credits/auto-refill-settings

Auth required.

curl https://api.ainative.studio/api/v1/credits/auto-refill-settings \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "success": true,
  "data": {
    "enabled": false,
    "threshold": 100,
    "amount": 1000,
    "payment_method_id": null
  }
}

Field	Description
enabled	Whether auto-refill is active
threshold	Credit level that triggers a refill
amount	Credits to purchase when triggered
payment_method_id	Stripe payment method to charge

---

Update Auto-Refill Settings

PUT /api/v1/credits/auto-refill-settings

Auth required.

Request body

Field	Type	Description
enabled	boolean	Enable or disable auto-refill
threshold	integer	Balance threshold (must be ≥ 0)
amount	integer	Credits to refill (must be > 0)
payment_method_id	string	Stripe payment method ID

curl -X PUT https://api.ainative.studio/api/v1/credits/auto-refill-settings \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": 500,
    "amount": 1000,
    "payment_method_id": "pm_xxx"
  }'

Response

{
  "success": true,
  "data": {
    "enabled": true,
    "threshold": 500,
    "amount": 1000,
    "payment_method_id": "pm_xxx"
  },
  "message": "Auto-refill settings updated successfully"
}

---

Active API Keys Count

GET /api/v1/credits/api-keys/count

Returns the count of active API keys for the current user. Useful for billing dashboards.

Auth required.

curl https://api.ainative.studio/api/v1/credits/api-keys/count \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "success": true,
  "data": {
    "active_api_keys": 3,
    "user_email": "user@example.com"
  }
}