How To Wire APIPod Into A Theme Demo Clip

Theme shops keep reshooting the same homepage demo every time a block moves. A cursor tour of the header is fine until the header changes, and then the MP4 is stale. APIPod is worth wiring in only if a new demo is one task you can retry without spawning a second, accidental render.

Screen recordings still win when the demo is a real click through the customizer. They lose when the shot is a short motion plate for the landing page: a product block sliding into place, a hero still easing into a pan. That plate is a video task, and the failure mode is a retry that creates a duplicate job while the first one is still running.

Name The Homepage Demo Before The Call

Name the clip the way you name a demo import. “Shop homepage, hero pan, five seconds” is a task. “Make the theme feel modern” is not. The video create call needs a model id and a prompt, and the prompt should describe that one shot. A theme release often has a dozen demos. Each demo is its own task, with its own key, because a retry has to know which body it is allowed to repeat.

Keep the source still or the prompt next to the theme version. When 7.9 moves a block, you can see whether the demo still matches the layout. A clip with no note about which demo it belongs to becomes an orphan file in the release folder. The request will not label it for you.

Prepare The Key And The Host First

APIPod serves the documented routes on the api host under /v1. The video create path is POST /v1/videos/generations. Send JSON as UTF-8 with Content-Type application/json, and send Authorization as a bearer token. Do that from the machine that builds the demo, not from a script you paste into a public snippet.

Keep The Bearer Key Off The Browser Bundle

The key stays in a server-side environment. A theme demo page that ships the bearer token in front-end JavaScript is a leaked key, and every visitor can spend on your account. The docs are plain about this: keys live on the backend, outside source control and browser bundles. If the demo site is static, the create call belongs on a small build server you control, and the page only receives the finished file.

A keyless call does not partially succeed. Account status without a key comes back missing the key, and a video create without a key comes back as an authentication error. There is no anonymous demo render to lean on while you “add the key later.”

Use The Async Host For A Video Task

The host api.apipod.ai applies a 120-second read timeout at the edge. That matters for a synchronous image call that might run longer than two minutes. Those long image calls are told to use the long-request host, with the same paths and the same authentication. A theme demo that is a video should not switch hosts to dodge that timeout. Video create is asynchronous on purpose, so it stays on api.apipod.ai. The create response comes back when the task is accepted. The pixels come back later.

If you point a video job at the long-request host because a previous image call needed it, you have mixed two patterns. Image edits that wait for the file use the long host. Video demos that return a task id use the normal host and a poll. Write that split into the build script so the next release does not “fix” it backward.

Send One Task And Store The Idempotency Key

Before the first POST, store an Idempotency-Key for that demo. The header is optional and strongly recommended on media create. The maximum length is 255 characters. The key is scoped to the API key, the HTTP method, and the route. A practical key is the theme version plus the demo slug, short enough to read in a log.

The Seedance API model id belongs in the JSON body, taken from the model page for the shot you are actually making. Store that body next to the idempotency key. A retry is safe only when both are unchanged.

Change The Body And The Old Key Breaks

Repeating the same key with an equivalent JSON body replays the stored response. The replay response carries X-Idempotent-Replay set to true. That is the outcome you want when the build server timed out and you are not sure the first POST landed. You get the original task, not a second one.

Reusing the key with a different body returns HTTP 409 and the code idempotency_conflict. Editing the prompt and sending again under the old key is that conflict. Mint a new key when the shot changes. Retrying while the first request is still in progress also returns HTTP 409, with the code idempotency_in_progress and Retry-After set to 1. Wait that second and retry the same body. Do not invent a new key just because the spinner is still up, or you will pay for two demos of one block.

Completed idempotency records are kept for seven days. A retry next week, after a theme patch, should not depend on the old key still replaying. Store the task id in the release notes when the create succeeds. The seven-day window is a safety net for a flaky build, not an archive of every demo you have ever rendered.

Poll Until The Status Is Terminal

A successful create returns an envelope with code 200, message success, and a task_id inside data. That envelope means the task was accepted. It does not mean the clip exists. Treat pending and processing as non-terminal. Stop only at completed, failed, or cancelled. Poll GET /v1/videos/status/{task_id} with the same bearer key, or configure a webhook if the build cannot sit in a loop.

Log the X-Request-ID from the create response next to the task id. When a demo fails, that pair is what you can hand to support. A build log that only says “video error” cannot be matched to a request.

1. Persist the idempotency key and the JSON body before the first POST.
2. Read task_id from the 200 envelope and store it before you poll.
3. Keep polling while the status is pending or processing.
4. On completed, copy the result file into storage you control. On failed or cancelled, stop and read the error instead of sending a new body under the same key.

APIPod will not hold the MP4 as your theme’s media library. The production note is to copy result URLs into durable storage. A demo URL that expires after the release is a broken player on the sales page. Download the file into the theme package while the status is completed.

Bounded backoff belongs on the poll, and on transient 429, 503, or other 5xx responses. A tight loop against status is how a demo build annoys the account without making the clip arrive sooner. If Retry-After is present, honor it.

When The Demo Clip Is Ready To Ship

Ship the clip when the status is completed, the file sits in your own storage, and the still or prompt still matches the theme version you are tagging. A pending task is not a demo. A replayed 200 from an old key is not a new shot of a block you changed this morning.

APIPod fits a theme shop that will keep the bearer key on the build server, store the idempotency key with the body, and poll until the status is terminal. It is a poor fit if the sales page is expected to render a fresh clip in the browser, with the key in the page, under a two-minute spinner. The edge timeout and the async envelope are there so you do not build that spinner.

The homepage can still use a screen recording when the point is a real click. Use the video task when the point is one motion plate you may have to retry without paying for it twice.