USD Console Quick Start

Choose the correct API

USD keys cannot call the credit-billed API. Neither balance automatically funds the other. Sign in with your existing Kolbo account to manage the console; keep API keys in your server's secret store, never in browser code or prompts.

1. Let your agent discover the contract

Set KOLBO_API_BASE to your deployment's /api/developer-console base. For local development, use http://127.0.0.1:5050/api/developer-console.

Read these public endpoints first:

• GET /llms.txt: short agent instructions and safety rules.
• GET /discovery: capabilities, endpoints and current availability.
• GET /openapi.json: machine-readable request and response schemas.
• GET /catalog?page=1&limit=100: model IDs, options, media and starting prices.

These four are public (no key) and share a limit of 30 requests per minute per IP. Catalog page accepts 1–1000 and limit 1–100; anything else returns 400 INVALID_PAGINATION. Follow nextPage until it is null. Use the exact model ID and an allowed request variant. Do not guess parameters from the model name or copy a different model's settings. Starting prices are not final quotes.

Authenticated endpoints (send X-API-Key):

Uploads are multipart/form-data with exactly one field named file and no other fields. They require a write-enabled key and return 201 with { "input": { "id", "kind", "contentType", "size", "width", "height", ..., "expiresAt" } }. No public URL is returned; pass input.id into the quote. Do not automatically retry an upload whose outcome is uncertain.

2. Obtain a fixed price

This request obtains a quote only. It does not start generation or charge funds.

curl "$KOLBO_API_BASE/quotes" \
  -H "X-API-Key: $KOLBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2-5","prompt":"A quiet mountain lake at sunrise","duration":4,"resolution":"720p","aspectRatio":"16:9","soundEnabled":true}'

Text-to-video requires model, prompt, duration (integer seconds), resolution, aspectRatio and soundEnabled (must be true), and omits operation and quality. Other request shapes select a variant with operation. Validate the body against discovery.requestSchemas.quote, then narrow it with the chosen model's quoteCapabilities; model limits can be narrower than the schema. Unknown fields are rejected.

Every media ID is a UUID returned by an upload endpoint for the same account. Per-model reference counts, durations and resolutions are in each catalog model's quoteCapabilities.

A quote response contains id, account, request (the normalized request), amountMicroUsd, currency (USD), expiresAt and generationEnabled. Media-input quotes other than image_to_video also return billableSeconds. Display amountMicroUsd / 1000000 as USD. Obtain the payer's approval for that amount. Check generationEnabled and expiresAt before submission. Video-input quotes require an account-owned inspected inputVideoId; input and output seconds may both be billable. Do not send a media URL in place of that ID.

3. Submit once, then track the same job

Before sending, durably save the quote id, the quote's account (the same value as GET /account account.id) and a fresh UUID as the idempotency key. The key must match ^[a-zA-Z0-9_-]{16,100}$. Submit only these fields:

{
  "quoteId": "THE_APPROVED_QUOTE_ID",
  "expectedAccount": "THE_QUOTE_ACCOUNT",
  "idempotencyKey": "YOUR_PERSISTED_UUID"
}

Send this body to POST /jobs with a write-enabled X-API-Key. Any other field returns 400 INVALID_JOB; an expectedAccount that differs from the key's payer returns 409 ACCOUNT_CHANGED. Never send a client-calculated price. A successful submission returns 202 with the job. Poll GET /jobs/{id} every five seconds while queued or running; slow down to thirty seconds for needs_attention.

A job contains id, account, model, status (queued, running, needs_attention, completed or failed), amountMicroUsd, currency, createdAt, chargedMicroUsd (non-zero only when completed), reservedMicroUsd (non-zero only while queued or running) and metadata. A failed job adds failure: { code, message }; a completed job adds result: { url, expiresAt } while the output is available.

• Completed: retrieve result.url before result.expiresAt. Stream the bytes into your own storage. Saving the URL alone does not retain the output.
• Failed: inspect the job's charged and reserved amounts; do not infer billing from the HTTP response alone.
• Unknown submission outcome: retain the same saved identity. Retry that exact payload or send it to POST /jobs/reconcile. Never create a new key merely because a request timed out.

Reconciliation does not start generation. It returns { account, status: "accepted", job } for an admitted attempt, or { account, status: "not_admitted" }, which permanently closes that unaccepted attempt. A reconciliation error is still unresolved, not permission to duplicate it.

Never send your API key to the result's media URL.

Limits and money

The current concurrency limit is 20 queued/running requests per account, shared across keys and the playground. Exceeding it returns 429 CONCURRENCY_LIMIT with Retry-After: 5, retryAfter: 5 and maxConcurrent: 20.

Rate limits are separate; honor Retry-After and retryAfter:

Apart from that public 429, errors are returned as { "error": { "code": "..." } }:

A quote normally expires within ten minutes, or earlier with its input. Outputs are retained for 30 days.

Wallet amounts use integer micro-USD. Catalog usdPerUnit values are already dollars per the indicated unit. Do not apply subscription-credit discounts or a second credit-to-dollar conversion. Manage top-ups, payment methods and automatic refill through interactive console login, not an agent's API key.