Use your AI credits

Video takes two requests, because a clip takes one to three minutes to render. The first starts the job and reserves its cost. It answers 202 with a job id and a poll_url. The second polls that job: 202 while it renders, then 200 with the clip URL in data[0].url.

curl "https://holdapi.lol/v1/videos/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{"model":"bytedance/seedance-1.5-pro","prompt":"a robot dog skating down a quiet street, slow dolly","duration_seconds":5,"resolution":"720p"}
EOF

Video models are priced per second, not per token. The reservation covers the duration and resolution you ask for; duration_seconds and resolution default to the model’s own, and each model has a maximum duration. Read both from /models, where a video row carries type: "video" and pricing.usd_per_second.

Credits are charged on the poll that finds the job completed, and the reservation is released in full if the job fails. Polling costs nothing and is safe to repeat: a finished job returns the same clip URL and the same charge however many times you poll it.

Name a clip length as duration_seconds, in whole seconds. A field the gateway cannot price a video by is refused with a 400 naming it, rather than passed on where it could cost more than was reserved. If the provider quotes more than the reservation, the job is abandoned, the reservation is released, and the response is a 502 with both figures.

Only the key’s own wallet can poll a job. A job id from another wallet returns 404. Keep the id: without it, the reservation stays held until it is reconciled against the provider’s ledger.

Append these paths to the base URL. Every endpoint requires Authorization: Bearer api_… with your full key. POST bodies use Content-Type: application/json.

curl "$OPENAI_BASE_URL/balance" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Before a request runs: the gateway reserves its estimated or quoted cost. Your available balance must cover the reservation, and the request must fit the per-call spending limit.

After the cost is known: usage-based billing settles the reservation to the provider’s reported cost and releases the difference. Quoted, prepaid requests are charged at the signed quote instead. Model pricing and the payment method affect the final cost.

Streaming responses and interrupted requests can leave a reservation pending until the provider’s cost is reconciled. A confirmed uncharged request releases its hold; a timeout alone does not confirm that a request was free.

If the final charge exceeds the reservation and your available balance, the unpaid amount is recorded. Future credit rewards first repay that amount before increasing your spendable balance. SOL rewards are not used to repay it.

Response headers include x-api-cost-micro-usd, x-api-reserved-micro-usd, and x-api-credits-remaining-micro-usd. For your current balance after a stream completes, read /balance or the dashboard.

One dollar equals 1,000,000 micro-USD. Creating another key does not create another balance or bypass the wallet’s limits.

Errors use an OpenAI-style JSON body with an error object. Read its code and message to distinguish errors with the same HTTP status.

400

Invalid request or model

Check the JSON body and use a full provider/model ID from the catalog. Choose the route for the model type.

401

Invalid API key

Use a complete, unrevoked api_ key from your dashboard. Send it as Authorization: Bearer followed by the key.

402

Insufficient credits

The balance must cover the reservation before a request starts. Check /balance, reduce max_tokens or the image count, or wait for more credits.

402

Request exceeds the spending limit

quote_over_limit means the estimate or quote is above the per-call ceiling. Reduce the requested output or image count; more balance alone does not lift this limit.

429

Too many requests

Slow down or reduce concurrent requests. Rate and concurrency limits are shared across your wallet’s keys.

502 / 503

Upstream service unavailable

Check your balance before retrying an uncertain request. A missing answer does not prove that the provider did not bill it.

If an answer is lost after a request is paid, retrying can create a second paid request. Check your balance and avoid blindly retrying an uncertain result.