Video generation (4-second clip)
POST /v1/videos/generationsText-to-video over x402 - one silent 4-second 720p clip (MP4, inline base64) for a flat $0.20, served by Veo 3.1 Lite. Send POST /v1/videos/generations with the required field prompt and pay $0.20 per call over x402 with USDC on an EVM chain or MPP. It returns a JSON object with created, model, data and usage.
Choose aspect_ratio 16:9 (default) or 9:16; duration, resolution and audio are fixed so the price is. The call returns when the clip is ready (about 40 seconds measured, up to 4 minutes). A failed or timed-out generation is not charged on x402, and a wallet payer whose request timed out can send it again unchanged to collect the same clip. Takes up to 4 minutes to answer: send the paid call with "Prefer: respond-async" to get a job link at once and collect the answer from it (on x402 the payment settles only on a delivered result), or with "Prefer: wait=240" and keep the connection open for at least 270 seconds, because a client that disconnects first loses the answer. A paid call with neither header is answered 400 before any payment is taken.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
prompt | string | yes | Text description of the clip (up to 2,000 chars) Also accepted as text, input, description, q, query. |
aspect_ratio | string (one of: 16:9, 9:16) | no | 16:9 (default, 1280x720) or 9:16 (720x1280) |
Example request
curl -i -X POST https://agent402.tools/v1/videos/generations \
-H "Content-Type: application/json" \
-d '{"prompt":"A paper boat drifting down a rain-soaked gutter, close up, cinematic","aspect_ratio":"16:9"}'Without payment this returns HTTP 402 Payment Required with the exact price for v1-videos; any x402 v2 or MPP client pays it and retries.
Watch a call get paid
POST /v1/videos/generations$0.20 USDCPAYMENT-SIGNATUREon 11 chains200 OKAgent402-ReceiptEd25519Example response
{
"created": 1750000000,
"model": "google/veo-3.1-lite",
"data": [
{
"b64_json": "AAAAIGZ0eXBpc29t…",
"media_type": "video/mp4",
"duration_seconds": 4,
"resolution": "720p",
"aspect_ratio": "16:9"
}
],
"usage": {
"generation_seconds": 40
}
}| Field | Type | Always present | In the example |
|---|---|---|---|
created | number | yes | 1750000000 |
model | string | yes | google/veo-3.1-lite |
data | array of objects | yes | 1 item in the example |
usage | object | yes | 1 field: generation_seconds |
From an MCP client
catalog.call {
"slug": "v1-videos",
"params": {
"prompt": "A paper boat drifting down a rain-soaked gutter, close up, cinematic",
"aspect_ratio": "16:9"
}
}The hosted connector at https://agent402.tools/mcp needs a payment for v1-videos; the stdio package pays it from a wallet or from an AGENT402_CREDITS_KEY issued earlier. Local install: npx -y agent402-mcp@0.14.0.
Errors and behavior
promptis required. An input the tool rejects returns an HTTP 4xx whose body carrieserror,tool,expected,requiredandexample, so the caller can correct it.- A paid call that ends in any status of 400 or above is not charged over x402, MPP or a prepaid credits key: settlement runs after the tool and only on a successful response.
- Wallet-only: this tool runs a model, so it has no proof-of-work tier. A prepaid card-credits key issued earlier (
Authorization: Bearer a402_...) also pays it. - Model-backed: the answer is generated by a model, so the same input can produce a different result.
- Sales tax: the price includes North Carolina sales tax for a buyer billed to a North Carolina address by card (a prepaid credits key or a card payment per call).
- Long-running: payment settles after the work finishes, so x402 is offered on EVM chains only and MPP on Base or Celo; Tempo is not offered.
- Usually answers in about 40 seconds and takes up to 240 seconds. Send the paid call with
Prefer: respond-asyncto get202and a job link at once, then pollGET /api/jobs/{id}for its stage, progress and ETA until it has the answer; payment still settles only when the answer is ready, except a Tempo transfer sent before the call, which is repaid after on-chain proof if the run fails. To wait on the connection instead, sendPrefer: wait=240and keep it open that long. A paid call with neither header is answered400before any payment is taken. - A
GETorHEADto /v1/videos/generations returns the same 402 quote, so the price can be read without a body. - An
Idempotency-Keyheader makes a retried paid call replay the first 200 instead of charging again (an answer larger than 1 MB and a streamed response are not replayed).
Paid call (JavaScript agent)
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const client = new x402Client();
client.setSpendControls?.({ maxAmountPerPayment: "$0.20" }); // refuse any quote above this tool's price
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);
const res = await payFetch("https://agent402.tools/v1/videos/generations", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"prompt": "A paper boat drifting down a rain-soaked gutter, close up, cinematic",
"aspect_ratio": "16:9"
}),
});Related tools
Fast image generation (OpenAI-compatible, budget)
Budget text-to-image over x402 - OpenAI images wire (prompt in, inline base64 out) at $0.02 per picture, a quarter.
Pro image generation (OpenAI-compatible)
Higher-fidelity text-to-image over x402 - OpenAI images wire (prompt in, inline base64 out) at $0.05 per picture.
Image edit (OpenAI-compatible)
Edit an image with a prompt (model-backed) over x402 - OpenAI images.edit wire (reference images and a prompt in, inline.
Text-to-speech (OpenAI-compatible)
OpenAI-compatible text-to-speech over x402 - point any OpenAI SDK's audio.speech.create() at base_url.
Chat completions (OpenAI-compatible)
OpenAI-compatible chat completions, base tier: point any OpenAI SDK at base_url https://agent402.tools/v1 and pay per.
Chat completions - auto tier (eval-ranked routing)
OpenAI-compatible chat completions with server-side model choice: omit "model" (or send "auto") and the gateway routes.