---
title: "Validate a request and estimate credits"
canonical_url: https://docs.zvid.io/docs/validate-and-estimate/
source: docs/validate-and-estimate.md
content_revision: 6338386a1dd87e4a
---

# 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](https://docs.zvid.io/docs/quick-start/) as `project.json`. The [downloadable Node.js example](https://docs.zvid.io/examples/render-once.mjs) wraps that file in `payload` and validates it by default:

```bash
node render-once.mjs project.json
```

Set `ZVID_API_KEY` in your environment first; obtain a key at [API keys](https://app.zvid.io/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:

```bash
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](https://docs.zvid.io/docs/endpoints/validate-render-job/) 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](https://docs.zvid.io/docs/templates/template-basics/) 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:

```bash
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](https://docs.zvid.io/docs/operations/render-lifecycle/).

For ChatGPT and other connected assistants, prefer the [MCP draft, quote and approval workflow](https://docs.zvid.io/docs/ai-assistants/). REST validation does not provide the MCP approval gate.

## Which schema should an assistant read?

Start with the [documentation resources](https://docs.zvid.io/docs/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.