kie.ai readiness check: is an API key found and where from, does the API respond, can the live price list be fetched, is the credit-to-USD rate set. Call this first whenever something is wrong.

Remaining credits on the kie.ai account. Cheap, no side effects.

Models with prices and limits. Prices are fetched live from kie.ai and never stored on disk, so they are always current; model schemas come from a 30-day cache. The first call in a session takes a few seconds while the price list is fetched.

Full model card: input schema, limits (max references, aspect ratios, duration), price. Call this BEFORE kie_generate.

Forces a full re-read: prices from kie.ai plus model schemas from the docs, ignoring the 30-day schema cache. Rarely needed — prices are fetched live on every call anyway. Use it when a model is missing or its parameters look wrong.

Record a model by hand: id, type, price in credits, limits. Stored separately from live data and applied on top of it — use this only for models the automatic price matching misses. Do NOT invent a price; take it from the documentation.

Cost estimate before generation. Spends no money. If known=false the price is unknown and generation must not start without user confirmation. If priceBasis="range", pass the same input and refs that will go into kie_generate: some models resolve an exact price from the parameters (resolution, presence of a reference) — see missingFields in the response.

SPENDS MONEY. Creates a generation task and, with wait=true, waits for the result and downloads the files. Before calling: kie_catalog_show (limits) and kie_estimate (price), plus the user's explicit consent to the amount. Use maxCostCredits as a safety limit. Downloading is ON by default (kie.ai keeps results for a limited time, up to 14 days per their docs): without out, the path from the config or ~/.gcv/output is used. noDownload=true skips the download entirely and leaves only the link.

Task state by taskId: state, progress, creditsConsumed, result links.

Wait for a task to finish, polling. Returns the final state.

Upload a local file to kie storage and get a public URL (lives 3 days). Needed for references.

Spend ledger: what was generated and what it cost. The source for a report to the user.