Usage & Billing

FireGuard bills guardrail work in tokens. Prepaid token credits are deducted from your organization balance at $2 per 1,000,000 tokens. Each guardrail phase is measured separately.

A typical protected turn can have two phases:

1. input_guardrails after the user message and before your model runs.
2. output_guardrails after the model response and before you return it.

What Affects Tokens

normal and fast execution modes use the same billing formula.

Text Tokens

Billable text matches what each guardrail scores:

When both policies and security run in the same phase, FireGuard bills max(policyTextTokens, securityTextTokens) — not twice.

Long Content (Runtime Only)

Long text is evaluated in overlapping windows of up to 20000 characters (2.5% / 500-character overlap). Each window is scored separately and results are merged:

Chunking affects scoring only. Billing uses the full billable text token count (plus image tokens on input), not the number of windows.

Media On Input (one call)

Pass images and documents on input_guardrails only — no separate upload endpoint.

Preferred ways (no client base64):

1. JSON sourceUrl — HTTPS URL Nest fetches into object storage, then runs guardrails.
2. Multipart — payload JSON field plus binary images / files parts on the same request.

Legacy: inline base64 on images[] / files[] still works.

Workers (OCR, policies multimodal, document extract) fetch stored objects via short-lived signed HTTPS URLs. Nest OBJECT_STORAGE_PUBLIC_ENDPOINT must be reachable by those workers (and allowlisted on vLLM --allowed-media-domains).

Python — sourceUrl

import requests

r = requests.post(
    "https://api.fireraven.ai/public/fireguard/v1/input_guardrails",
    params={"conversation_id": CONVERSATION_ID},
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "messages_history": [{"role": "user", "content": "What's in this image?"}],
        "images": [{
            "sourceUrl": "https://cdn.example.com/photo.png",
            "mimeType": "image/png",
            "name": "photo.png",
        }],
    },
)
print(r.status_code, r.text)

Python — multipart

import json
import requests

payload = {"messages_history": [{"role": "user", "content": "Review this attachment"}]}
with open("photo.png", "rb") as img, open("note.pdf", "rb") as doc:
    r = requests.post(
        "https://api.fireraven.ai/public/fireguard/v1/input_guardrails",
        params={"conversation_id": CONVERSATION_ID},
        headers={"X-API-Key": API_KEY},
        files=[
            ("payload", (None, json.dumps(payload), "application/json")),
            ("images", ("photo.png", img, "image/png")),
            ("files", ("note.pdf", doc, "application/pdf")),
        ],
    )
print(r.status_code, r.text)

Do not set Content-Type yourself on multipart — the client must add the boundary.

Images On Input

Only input_guardrails accepts top-level images[].

Each image item requires mimeType and exactly one of:

Do not send server-filled url.

Limits (defaults; a deployment may tighten these without changing the API shape):

• Up to 6 images per request.
• Up to 3 files per request.
• Up to 5 MB (5,242,880 bytes) per image or document.
• Up to 15 MB (15,728,640 bytes) total across images only in one request (files have no combined size cap beyond 3 × 5 MB).
• Legacy base64: up to ~7M characters per item; ~21M total across images.
• Send images in images[], not inside messages_history[].content.

Policies use images for multimodal scoring with the last messages. Security does not receive raw bytes in the classifier; it uses OCR and metadata text combined with the last messages.

Files On Input

Only input_guardrails accepts top-level files[] (up to 3). Each file is capped at the same 5 MB per-object limit as images; there is no separate total across files[]. Supported documents:

• PDF (.pdf)
• Word (.docx)
• Excel (.xlsx)
• Plain text (.txt)
• Markdown (.md)

API mimeType values are listed in the Input guardrails reference. Each file item uses mimeType and exactly one of sourceUrl (preferred), storageKey, or legacy base64, plus optional name. Multipart files parts use the same limits.

Before guardrails run, FireGuard extracts text and images from the files (from object storage after ingest), appends the text to the last user message, and merges extracted images with any client images[] (hard cap still 6, client images first). Token billing uses that expanded text and image set. If extraction fails while files were sent, the request fails with 503 (file content is not silently skipped).

Image Tokens

When policies or security run on input, each image adds tokens. Prefer pixel dimensions when base64 is still present; for stored objects the service bills from size metadata.

Image tokens are added once per input phase on top of text tokens.

Credits And Limits

Token credits and daily request limits are independent checks:

The daily limit counts requests, not tokens: each successful FireGuard phase (input_guardrails or output_guardrails) increments the counter by 1. The limit resets on a UTC calendar day. The default organization cap is 1,000,000 requests per day unless Fireraven configures a different limit for your organization.

Buy credits and view balance in Organization Settings under Plan and Usage. Eligible organizations can claim 2.5M free tokens (~$5 at $2 / 1M) from the in-app free-credits onboarding.

Next Steps