Understand API billing
API tasks draw from the same subscription credit balance you use on the VidMage website. Access and available credits are separate checks.
API credit rates and estimates
API product pages show rates and example request costs in credits, derived from the same configuration and quote functions used by the API. Examples list the duration and settings used to calculate the total.
Resolution, audio, output count, reference media, rounding, and minimum charges can affect the total. Talking Photo adds video and speech charges; Lip Sync uses the selected workflow rate.
Use estimate_model_credits for models and estimate_capability_credits for features, or estimate your request in the Playground. These estimates do not start a generation. Actual task usage is recorded separately.
An active subscription is required. Website and API activity share the same balance. See current plans and credit packs for purchase prices.
Subscription access and credit balance
| Response | Meaning | Action |
|---|---|---|
403 NEED_SUBSCRIBE | The account needs an active subscription. | Activate or renew the plan. |
402 NEED_PURCHASE_CREDITS | The operation needs more credits. | Add credits or select a lower-cost operation. |
See the current pricing page for plans and the selected API product for its available controls. Website and API activity use a shared balance, so a separate website task can change the balance available to an API request.
Read the task usage fields
| Field | How to use it |
|---|---|
creditsRequired | The task requirement shown by responses that include this field. |
creditsConsumed | The recorded consumed credits. Retain it with your task record. |
usageDeferred | Signals deferred usage in responses that include this field. A zero consumed value at submission is not a zero-cost promise. |
The published AI Photo Face Swap submit example includes creditsRequired, creditsConsumed: 0, and usageDeferred: true. Check the actual response for your task rather than treating an initial usage field as the final charge.
For model workflows in MCP, list_models and estimate_model_credits provide the documented discovery and estimate sequence. An estimate is distinct from a completed task usage record.
For feature capabilities, including AI Talking Photo and AI Lip Sync, use estimate_capability_credits. The documented estimators are read-only and consume no credits. Use their current argument schemas and keep the estimate with the chosen input settings.
Read usage without treating missing values as zero
This local example reads your saved submission response. It makes no API call and invents no charge. The three field names come from the published AI Photo Face Swap submit example; other operations or stages may omit them.
import json
from pathlib import Path
response_path = Path("submit-response.json")
response = json.loads(response_path.read_text())
fields = ("creditsRequired", "creditsConsumed", "usageDeferred")
usage = {name: response[name] if name in response else None for name in fields}
print(json.dumps(usage, indent=2))null means the saved response did not report that value. An explicit 0 remains zero. If usageDeferred is true, keep observing the existing task and reconcile its final usage or billing record before calling that amount final.
Capture estimates with the same model, input mode, media, duration, resolution, and output-count settings you intend to submit. A later settings change needs a matching estimate. Keep the final task-level record; a shared account balance change alone cannot isolate the cost of one task when other work is running.
Separate failed tasks from uncertain outcomes
Confirmed failures are automatically refunded only when the refund outcome is certain. Unknown provider, billing, or refund outcomes remain pending reconciliation.
| Outcome | Action |
|---|---|
| Confirmed failure with a clear refund outcome | Record the failure and refund state before starting a corrected task. |
BILLING_OUTCOME_UNKNOWN | Follow the returned recovery action. Do not resubmit or create a new idempotency key. |
REFUND_OUTCOME_UNKNOWN | Do not request another refund for the same task. Preserve identifiers for support. |
BILLING_INVARIANT_FAILED | Stop retries and contact support with the original identifiers. |
Keep a small usage record per task
Store the capability, task ID, original idempotency value, request ID, and returned usage fields. These let you connect a charge or refund to the operation that caused it without logging your API key.
Rate and concurrency limits apply to the stable API key. After a 429, follow Retry-After and keep querying existing tasks. See task recovery and billing error recovery for the next action.