Idempotency

Why

A network error can leave you not knowing whether a job was created. Sending the same request again must not create (and charge) a second job. That is what Idempotency-Key is for.

With an Idempotency-Key

Send a header of 1 to 255 printable ASCII characters, unique per intended job, for example a UUID:

POST /v1/generations
Idempotency-Key: 7d1c0f6e-5b0a-4a33-9f2e-0c1b2a3d4e5f

• The first request creates the job and answers 201.
• Repeating the request with the same key and the same body returns the same job with 200 and Idempotent-Replayed: true. You are charged once, also when the repeats run at the same time.
• Using the same key with a different body returns 409 idempotency_conflict.
• Keys are remembered for as long as the job exists.

Generate a new key (for example a UUID) for every new job, and send the same key again when you retry the same request after a network error or a 5xx. Never reuse a key for a different job.

Without a key

If you send no key, CheapVids still protects you against double submits: an identical request within 120 seconds (same account, same endpoint, same body) returns the first job instead of creating a new one. After 120 seconds the same body creates a new job.

If a duplicate arrives while the first request is still being processed, it waits up to 3 seconds for the result; if the first request is not finished by then it answers 409 idempotency_conflict ("duplicate request in progress"), and you can retry.

Several variants of one prompt

Because identical requests collapse into one job, to get several variants of the same prompt send a different Idempotency-Key on every call (or change a parameter):

import requests

for i in range(4):
    requests.post(
        "https://api.cheapvids.com/v1/generations",
        json={"plan": "credits", "model": "nano-banana-2", "params": {"prompt": prompt}},
        headers={"Authorization": "Bearer cv_live_YOUR_KEY", "Idempotency-Key": f"variant-{batch_id}-{i}"},
        timeout=120,
    )

The OpenAI compatible endpoint

The OpenAI client libraries retry on 5xx and timeouts with the same body and no key. The 120 second rule above returns the original job, so a retried request after 504 generation_pending does not charge twice. See OpenAI compatibility.