Build with a coding agent

Give your coding agent one prompt. It reads your project and these docs, then adds VizoAPI on your server.

1. Send the prompt to your agent

   Paste it into Claude Code, Codex, Cursor or any agent that can read your code. The prompt is in English; your agent replies in your language.

   # Task: integrate VizoAPI into this application
   
   Follow this project's own instructions. Treat the VizoAPI documents as reference, not as permission to change unrelated features, publish or deploy.
   
   Step 1. Look before you edit. Inspect the project: framework, server routes, background jobs, storage, user or tenant model, and any code that already calls an image, video or audio generation API. If an integration exists, list every call site with its provider, exact model, input fields and file location. Keep what is configured apart from what is actually called, and list unknowns instead of guessing. If the project has no integration yet, confirm with me what the feature must do before you build it. Do not read or print secret values.
   
   Step 2. Read the documentation. Start at https://vizoapi.com/docs and the quickstart https://vizoapi.com/docs/first-video, then read the API reference pages you need. Every docs page also exists as Markdown at the same address with ".md" added. The full index is https://vizoapi.com/llms.txt and the OpenAPI document is https://vizoapi.com/docs/openapi.json. Also read Rate limits https://vizoapi.com/docs/rate-limits, Billing https://vizoapi.com/docs/billing, Errors https://vizoapi.com/docs/errors. After you choose a model in step 4, read its guide, https://vizoapi.com/docs/models/<model id>.md. Use only the endpoints and fields documented there. Do not invent an SDK, a package name or an endpoint.
   
   Step 3. Authentication and base URL. Every API call goes to the API host, not the website:
   https://api.vizoapi.com
   Read the base URL from the server-side environment variable VIZO_API_BASE_URL, with that value as the default, so a test environment can point elsewhere. Send Authorization: Bearer <key> and Content-Type: application/json. Read the key from the server-only environment variable VIZO_API_KEY, and never store the word Bearer in it. Keep every authenticated call on the server. Never ask me for the key in this chat, and never put it in browser or app code, logs or the repository.
   
   Step 4. Choose the model. Call `GET /v1/models` and `GET /v1/models/{id}` to find the model for each use case. Read its `inputSchema`: the fields, resolutions, durations and aspect ratios it accepts, in the model's own field names. Read its `features` and the price of each of its `tiers`; the input alone selects the tier. Check the model's input limits (how many images, videos and audio files, and how long) and enforce them on the server. Prefer the same model and version the project uses today, and never treat a similar name as the same model. If no documented model fits, stop and ask me. Then read the model's guide, https://vizoapi.com/docs/models/<model id>.md, and start from its example bodies: it lists the modes the model supports with a runnable body for each, its input limits, how its price is held and charged, and the errors it returns. To validate a body without creating anything, send it to `POST /v1/estimates`: it is free, creates no task, holds no Credits and refuses invalid input with the same errors as a create. It needs the generations:create scope and counts against the rate limits.
   
   Step 5. Create the task. Call `POST /v1/generations` with `model` and `input`. Build `input` from the schema: for Kling and Wan the prompt goes in `input.prompt`, for Seedance and MiniMax in a text part of the input's content list. Send only the fields the schema lists, such as `input.resolution` and `input.duration`; any other field is refused with HTTP 422. Check the same allowed values in the form, on the server and in the request body. Add `metadata` with a `client_reference` of your own, such as your order id. Store the task `id` together with the user or tenant that created it. The call returns HTTP 202 at once; the result comes later.
   
   Step 6. Never repeat a create call blindly. Each accepted create call is a separate task and a separate charge. Turn off automatic retries for this POST in the HTTP client and in any proxy, and stop the user from submitting the same form twice. If a create call times out or disconnects, do not send it again: first look for the task with `GET /v1/generations` and the same `client_reference`. A 429 response means no task was created: wait the number of seconds in the Retry-After header, then try again. By default an organization runs 3 video tasks at once (10 image, 10 audio); a create above that gets 429 concurrency_limited, so keep your own queue and submit the next task when one finishes.
   
   Step 7. Wait for the result. Poll `GET /v1/generations/{id}` every 5 seconds, slowing to every 10 seconds, with an overall time limit. The task is finished when `closed_at` is not null. If `status` is "succeeded", take every `asset_id` in `result.outputs`, in order; a task with one output lists one. `result.asset_id` repeats the first output, so do not download it twice. While the task runs, `status` is "processing". There is no cancel call: stopping the polling does not stop the task, and it runs to the end and is charged if it succeeds. Do not build a cancel button. A task can still end as "canceled" when the system closes it, for example when it was not started in time; it is not charged. A task still unfinished at its deadline (24 hours after acceptance by default) closes as "unresolved": its hold is released and it is not charged, so treat it as failed. If its result arrives later anyway, the task sets `late_result_available` to true and gains a `result` at no charge (webhook event `generation.late_result_available`). Check that the task belongs to the current user before you show its status or result.
   
   Step 8. Download and keep the output. Call `GET /v1/assets/{id}/download` and fetch the returned `url` at once, without the API key, because it expires at `url_expires_at`. Copy the file to your own storage: outputs are kept for 7 days only. If the task did not succeed, read `error.code` and show the user a clear message. To send an input image, video or audio file, upload it first: `POST /v1/assets/uploads` with `mime` and `max_bytes`, PUT the bytes to the returned `upload_url`, then call `POST /v1/assets/{id}/complete`, and put the `asset_id` where the schema expects the media. A media field also takes a public HTTPS URL. A local file path is not an asset.
   
   Step 9. Webhooks, if you want them instead of polling. Create the endpoint in the console, then pass `webhook_endpoint_id` when you create the task. A delivery is a POST signed per the Standard Webhooks specification, with the headers webhook-id, webhook-timestamp and webhook-signature. Verify it with the official Standard Webhooks library for the language (standardwebhooks on npm and PyPI) and the endpoint's whsec_ signing secret, passing the raw request body; the library checks the signature and the 5-minute timestamp window. Ignore a webhook-id you have seen. Then read the task with `GET /v1/generations/{id}` and act on that read.
   
   Step 10. Errors and cost. Handle a missing or invalid key (401), too few Credits (402), invalid input (422), too many requests (429) and server errors (500, 503). Retry reads with backoff; never retry a create call except after a 429. Prices are in Credits: read the charge from `price.charged` on the task and the balance from `GET /v1/wallet`, which needs a project key with the balance:read scope. The charge follows actual usage and can be above the estimate; Credits the balance cannot cover are owed, and new creates get 402 balance_negative until a top-up. Inputs and outputs are always moderated, with no switch; a refused task usually fails with input_moderated or output_moderated, but on some models (Kling) with generation_failed, and either way it is not charged. Do not hard-code prices.
   
   Step 11. Finish. Run the project's checks and tests. Tell me what changed, which server environment variables to set, how to try the feature, and what is still unverified. A passing local check is not proof that a live call works. Ask me before any live call that costs Credits, and before you deploy.

2. Create an API key

   Set it on your server as VIZO_API_KEY. Never paste the key into the agent chat.

   Create API key

3. Review and test

   The agent lists what it changed and asks before any call that spends Credits. Run one small task, then ship.

Moving from Replicate, fal.ai, WaveSpeed or kie.ai? The migration prompts map that provider’s calls one by one.

Agents can read the whole documentation from llms.txt.