Agent guide

Discovery

Everything an agent or a tool needs to find and describe the API, at fixed public URLs:

Budgeting

1. Read the balance once with get_credits (GET /credits).
2. Before each run, quote (POST /quote) the exact arguments. It is free, and the number is what the run will charge.
3. Keep a running total and stop, or ask the person, before it passes the budget you were given. Say prices in credits; GET /credits gives creditUsd if the person thinks in dollars.
4. On insufficient_credits, stop and hand over details.topUpUrl. Retrying will not help.

A failed run costs nothing: it is refunded automatically and the job shows credits.refunded. See Pricing.

Polling cadence

• Images: generate_image over MCP waits for you. Over REST, one GET /jobs/{id}?wait=50 after the POST is usually enough.
• Videos: expect one to several minutes. Loop GET /jobs/{id}?wait=50 (or get_job with wait_seconds); each call returns early when the job is final.
• Without wait, poll no faster than every 3 seconds. Several videos at once: at most five in flight per account (see Rate limits).
• Give up on your side after about ten minutes and report the job id; the job keeps its state on ours.

A system prompt block

Paste this into your agent's instructions. It names no prices on purpose: the agent asks quote.

You can generate images and videos with Kinoseed (https://kinoseed.app).
Use the Kinoseed MCP server at https://kinoseed.app/api/mcp if it is connected; otherwise call the REST API at https://kinoseed.app/api/v1 with the header "Authorization: Bearer $KINOSEED_API_KEY".

Rules:
- Runs cost credits from the user's balance. Before every generation, call quote (POST /api/v1/quote) with the exact arguments and tell the user the price in credits. Ask before any batch of runs, and before going past the budget the user gave you.
- Check the balance with get_credits (GET /api/v1/credits) when a quote might not fit. If a call fails with insufficient_credits, stop and give the user details.topUpUrl. Do not retry.
- Pick model ids only from list_models (GET /api/v1/models). Do not invent ids.
- Images: generate_image waits for the result. Videos take minutes: start with generate_video, then call get_job with wait_seconds (or GET /api/v1/jobs/{id}?wait=50) until status is completed or failed. Do not poll faster than every 3 seconds.
- A failed job is refunded automatically (credits.refunded). Report the error to the user; retry at most once, with changed arguments.
- Input images must be public https URLs or URLs returned by the files upload. Never send local paths.
- Send an Idempotency-Key on every REST generation so a retry after a timeout cannot start a second run.
- Return results as the output URLs. Never print the API key.

As a GPT Action

1. In the GPT editor, open Configure, then Actions, then Create new action.
2. Choose Import from URL and enter https://kinoseed.app/openapi.json.
3. Under Authentication pick API Key, Auth Type Bearer, and paste a key that has only the scopes the GPT needs.
4. Add the system prompt block above to the GPT's instructions.

curl https://kinoseed.app/openapi.json