Billing and usage

Add USD credit

BeefAPI uses prepaid USD credit. Open Billing, choose an available checkout option, and wait for the confirmed credit to appear in your balance. Returning from checkout alone does not confirm payment.

Your global wallet and API keys belong to global.beefapi.com. Credit on the Chinese site is separate. An API key with an unlimited spending limit still needs enough account credit.

How requests are priced

Cache usage is not automatically free. Where a model has long-context pricing, the applicable rates can rise for the request. Use the recorded token categories and any pricing details in Usage to understand the final charge; do not count cached tokens twice as both ordinary input and cache input.

Current prices as JSON

Pricing and pricing.usd.json read the same global USD pricebook:

curl --fail-with-body https://global.beefapi.com/pricing.usd.json

This is a current base-price catalog, not a quote for every possible request. Long-context adjustments and actual usage can affect the final text charge. The account's usage record is the final charge for that request.

The separate /pricing.json endpoint is a shared catalog with a different currency/schema contract. Use /pricing.usd.json for global USD integrations.

Reserved credit and settlement

BeefAPI may reserve credit before a request runs. A request can therefore be rejected for insufficient credit even when the displayed balance is above zero: it must cover the estimate and other work already in flight.

After the request is accounted for, the reservation is reconciled with its charge. Video jobs reserve their estimated cost at creation. A task recorded as failed releases its reservation through failure processing.

A client timeout or lost connection is not proof of cancellation or a refund. For a video or image job, poll the saved task/job ID. For a synchronous call with an uncertain outcome, check Usage before sending it again. A second generation is a separate request and can be charged separately.

Read your usage

Open Usage to inspect the model, time, request ID, and USD cost. Text calls may also show input, output, and cache token details. Keep the request or task ID if a charge needs investigation.

For programmatic account access, API reference explains the system access token and account fields. Raw quota fields are accounting units, not USD amounts; use the console's USD display rather than a guessed conversion.

Query key usage

Use the same Bearer API key you use for model requests. No account access token or browser session is needed. Each key can read only its own global USD usage.

Set BEEFAPI_API_KEY in your environment, then query a time range using Unix timestamps (UTC):

curl --fail-with-body --get 'https://global.beefapi.com/v1/usage' \
  --header "Authorization: Bearer $BEEFAPI_API_KEY" \
  --data-urlencode 'start_time=1788998400' \
  --data-urlencode 'end_time=1789084800'

Replace the timestamps with your reporting period. Start is inclusive and end is exclusive. Without dates, the API returns the last 30 days; the maximum range is 31 days. Optional model selects one exact model ID. The response includes currency: "USD", settled_amount, pending_amount, refunded_amount, unknown_records, by_model, and daily UTC totals in daily. Amounts are decimal strings.

settled_amount is the net settled amount, already including recorded refunds. Do not subtract refunded_amount again. Pending amounts are separate and may change. This reports recorded usage, not your account balance or every reservation currently in flight. records counts usage records, not unique HTTP requests. A request can have both an error record and a charge record.

Look up a request

curl --fail-with-body --get 'https://global.beefapi.com/v1/usage/requests' \
  --header "Authorization: Bearer $BEEFAPI_API_KEY" \
  --data-urlencode 'request_id=YOUR_REQUEST_ID'

Use the dates of the request for records older than 30 days. An original funding request can resolve to its later settled receipt when that link was recorded. Other client retries remain separate requests.

Each item in data includes a stable record id, request_id, created_at, model, recorded input/output/cache token counts, and:

usage_estimated: true means the usage measurement was estimated. It is separate from settlement: a recorded final charge can be based on estimated usage.

A missing record, an unknown billing state, or an error record without an amount does not prove that the request was free. Settlement can arrive later. Keep the request ID and check again before retrying a costly operation.

Read more than one page

Omit request_id to list records. Set limit to 1–100 (default 50). When has_more is true, pass next_cursor as before on the next request. Keep start_time, end_time, and model unchanged. Records are ordered newest first; pending records can be updated in place, so refresh the reporting window to reconcile later settlement.

IP-restricted keys can query only from an allowed address. Expired, disabled, or exhausted keys can still read their retained records. Deleted keys and blocked accounts cannot. Missing or invalid credentials return HTTP 401; site or account access restrictions return 403. Invalid filters return 400; rate limits return 429; an unavailable query returns 503. Never put a key in a query string or share it in a screenshot.

See the full usage summary reference and request records reference.

Refunds and payment issues

For a payment refund, read Refunds and email support from your account email with the order reference shown in Billing. Payment refunds are reviewed against the original payment and are separate from releasing a failed API task's reservation.

If checkout reports success but credit has not appeared, keep the order reference and contact support before paying again.