Validate a request and estimate credits
Call POST https://api.zvid.io/api/render/validate/api-key before submitting a new composition or variable set. This authenticated, free operation resolves the request and applies account limits without creating a render job or reserving render credits.
Use the same request envelope that you intend to render: exactly one of payload (inline project) or template (stored template ID), with optional variables and overrides. Inline projects also pass through variable resolution. A project by itself is not the REST request envelope.
Validate an existing project file
Save the project from Quick start as project.json. The downloadable Node.js example wraps that file in payload and validates it by default:
node render-once.mjs project.json
Set ZVID_API_KEY in your environment first; obtain a key at API keys. The example needs Node.js 20 or newer. Do not place a real key in a project, prompt, source repository or browser application.
If you already have a request envelope, save it as request.json and use:
node render-once.mjs request.json --request
The example prints the validation response. Read creditsRequired and warnings, then inspect the resolved payload. valid: true confirms the submission checks succeeded; it does not prove that remote media will remain available or that every visual detail looks good.
Interpret the result
| Result | Meaning | Next action |
|---|---|---|
HTTP 200, valid: true | Request resolves and passes current validation | Inspect the resolved project, warnings and credit estimate |
| HTTP 400 | Invalid request, unresolved data or a validation/plan-limit problem | Read error, message and details; correct the indicated fields |
| HTTP 401 | Missing or invalid authentication | Check the API key and header |
| HTTP 503 | Service temporarily unavailable | Retry validation later with a bounded delay |
The validation endpoint reference describes the full response. Some SDKs normalize validation errors into valid: false; the REST API uses HTTP errors for invalid requests. Check the contract of the interface you use.
Resolve warnings before spending credits
Warnings can identify layout or readability problems that a structural schema cannot reject. Check text bounds, aspect ratios, empty scenes, source URLs, subtitles and overlap timing. When a warning is intentional, record why; do not silently discard warnings in an automation.
Use template preview when you specifically need a stored template's resolved {project, stats}. Preview is also free, but its response differs from validation. It does not return a job or rendered media.
Render the reviewed request
After reviewing the estimate, explicitly enable rendering:
node render-once.mjs request.json --request --render
This example validates again, submits once, prints the job ID, then polls with a deadline. Rendering spends credits. A successful validation is an estimate at that moment, not a reservation or a guarantee of future balance or capacity. Preserve the job ID and follow the render lifecycle.
For ChatGPT and other connected assistants, prefer the MCP draft, quote and approval workflow. REST validation does not provide the MCP approval gate.
Which schema should an assistant read?
Start with the documentation resources. The authoring schema covers projects containing template expressions; the resolved-project schema covers values after resolution; the render-request schema covers the REST envelope. Local schemas help catch structural errors. Authenticated validation remains authoritative for the current account, template resolution, semantic checks and credit estimate.