DEV Community: Mina Ramzy

Bulk AI Video Generation API: How to Generate 1,000 Videos

Mina Ramzy — Tue, 09 Jun 2026 21:00:00 +0000

To generate 1,000 videos automatically with a bulk AI video generation API workflow, start with one reusable JSON video template, map each row of source data into that template, submit one render job per output, and poll each job until it completes or fails. The important architecture is not just "send 1,000 requests." A reliable bulk video generation API workflow needs idempotent job IDs, queue-aware submission, retry rules, payload versioning, and a place to store the final render URLs.

Zvid is built for the rendering layer of this pattern because each video can be described as structured JSON and submitted to POST https://api.zvid.io/api/render/api-key. Your application then polls GET https://api.zvid.io/api/jobs/{id} for progress and result URLs. If AI models generate scripts, prompts, reference images, or source clips upstream, Zvid can still provide the repeatable video creation endpoint that assembles approved assets into completed videos. Keep the Getting Started guide, Submit render job reference, Get render job status reference, and JSON Structure overview open while you design the workflow.

Bulk video generation works best when data mapping, render submission, and job polling are separate steps.

If you are new to JSON-driven rendering, start with How to Generate a Video from JSON, then compare this bulk workflow with the broader JSON to Video API guide, the feed-driven pattern in How to Create Product Videos from a CSV or Product Feed, and the timed media model in How to Add B-roll Automatically with JSON.

The public API loop is simple:

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @render-job.json

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

The bulk version of that loop adds orchestration around the API call: validate data, generate payloads, submit jobs at a controlled pace, poll active jobs, store completed URLs, and retry failures only when the failure is retryable.

The bulk video generation architecture

A high-volume video workflow has five parts:

A data source, such as a CSV export, product feed, CRM list, campaign table, or database query.
A template mapper that turns each record into a Zvid JSON payload.
A submission queue that controls how many render jobs are created at once.
A polling worker that checks job status and records final results.
A review and delivery layer that stores URLs, thumbnails, errors, and source payload versions.

Separate data mapping, queue control, rendering, polling, and delivery so each stage can be retried independently.

This architecture helps teams avoid the main failure mode in bulk rendering: losing track of which source record produced which job, which payload version was used, and whether a failure should be fixed in data, template logic, media assets, or orchestration code.

For a production system, store at least the source record ID, template version, generated payload, submitted job ID, current job state, error details, completed video URL, and timestamps. That record becomes the audit trail for every generated video.

Copy-paste Zvid bulk render payload

The renderable payload below demonstrates a single output from a bulk campaign. In a real 1,000-video workflow, your application would generate a variation of this payload for each source record by changing the title, audience segment, CTA, accent color, media URLs, or output format.

{
  "name": "bulk-video-generation-api-demo",
  "resolution": "hd",
  "duration": 9,
  "frameRate": 30,
  "outputFormat": "mp4",
  "backgroundColor": "#07111F",
  "visuals": [
    {
      "type": "SVG",
      "width": 1280,
      "height": 720,
      "track": 1,
      "svg": "<svg width='1280' height='720' viewBox='0 0 1280 720' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='bg' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#07111F'/><stop offset='1' stop-color='#17233D'/></linearGradient><linearGradient id='accent' x1='0' y1='0' x2='1' y2='0'><stop offset='0' stop-color='#2DD4BF'/><stop offset='1' stop-color='#FADD46'/></linearGradient></defs><rect width='1280' height='720' fill='url(#bg)'/><rect x='64' y='70' width='1152' height='580' rx='30' fill='rgba(255,255,255,0.045)' stroke='rgba(255,255,255,0.14)'/><text x='104' y='136' fill='#FFFFFF' font-family='Arial' font-size='32' font-weight='800'>Bulk render run</text><text x='104' y='176' fill='#BFC7DE' font-family='Arial' font-size='20'>One template becomes many API jobs</text><rect x='104' y='232' width='250' height='290' rx='24' fill='rgba(7,13,30,0.8)' stroke='rgba(255,255,255,0.13)'/><text x='229' y='284' text-anchor='middle' fill='#2DD4BF' font-family='Arial' font-size='24' font-weight='800'>Data rows</text><circle cx='156' cy='340' r='14' fill='#2DD4BF'/><rect x='190' y='326' width='110' height='16' rx='8' fill='rgba(255,255,255,0.35)'/><circle cx='156' cy='394' r='14' fill='#2DD4BF'/><rect x='190' y='380' width='128' height='16' rx='8' fill='rgba(255,255,255,0.35)'/><circle cx='156' cy='448' r='14' fill='#2DD4BF'/><rect x='190' y='434' width='92' height='16' rx='8' fill='rgba(255,255,255,0.35)'/><rect x='456' y='232' width='310' height='290' rx='24' fill='rgba(7,13,30,0.8)' stroke='rgba(255,255,255,0.13)'/><text x='611' y='284' text-anchor='middle' fill='#FADD46' font-family='Arial' font-size='24' font-weight='800'>JSON template</text><rect x='502' y='326' width='218' height='18' rx='9' fill='rgba(250,221,70,0.4)'/><rect x='502' y='366' width='168' height='18' rx='9' fill='rgba(255,255,255,0.25)'/><rect x='502' y='406' width='204' height='18' rx='9' fill='rgba(255,255,255,0.25)'/><rect x='868' y='232' width='270' height='290' rx='24' fill='rgba(7,13,30,0.8)' stroke='rgba(255,255,255,0.13)'/><text x='1003' y='284' text-anchor='middle' fill='#FFFFFF' font-family='Arial' font-size='24' font-weight='800'>Render queue</text><rect x='912' y='326' width='184' height='42' rx='14' fill='rgba(45,212,191,0.18)' stroke='rgba(45,212,191,0.55)'/><rect x='912' y='388' width='184' height='42' rx='14' fill='rgba(250,221,70,0.16)' stroke='rgba(250,221,70,0.5)'/><rect x='912' y='450' width='184' height='42' rx='14' fill='rgba(255,255,255,0.12)' stroke='rgba(255,255,255,0.24)'/><path d='M370 376 H428' stroke='url(#accent)' stroke-width='8' stroke-linecap='round'/><path d='M782 376 H840' stroke='url(#accent)' stroke-width='8' stroke-linecap='round'/><rect x='246' y='574' width='788' height='36' rx='18' fill='rgba(255,255,255,0.1)'/><rect x='246' y='574' width='560' height='36' rx='18' fill='url(#accent)'/><text x='640' y='638' text-anchor='middle' fill='#C8D2F1' font-family='Arial' font-size='18'>Submit, poll, store, retry only when needed</text></svg>"
    }
  ]
}

The payload visual is generated from the real renderable bulk workflow example.

For the public render endpoint, wrap the project inside a top-level payload field:

{
  "payload": {
    "name": "bulk-video-generation-api-demo",
    "resolution": "hd",
    "duration": 9,
    "frameRate": 30,
    "outputFormat": "mp4",
    "visuals": []
  }
}

How the API workflow works

In a single render, your application builds one payload, submits it, and polls one job. In bulk rendering, the same steps happen many times, so the orchestration layer matters as much as the payload.

A bulk renderer should keep source records, payloads, job IDs, and final URLs connected.

A practical implementation looks like this:

Read a batch of source records from your database, CSV, CMS, or product feed.
Normalize values so every record has safe text, color, media URL, and timing fields.
Generate one Zvid payload per record using a versioned template.
Submit jobs through the render endpoint at a controlled concurrency.
Store each returned jobId next to the source record and payload version.
Poll the jobs endpoint until each job is completed or failed.
Save result.url for completed jobs and store failedReason for failed jobs.

This structure gives you a clean answer to the most important operational question: "What happened to this specific video?" You can trace each result from original data to payload to render job to final URL.

Design the job queue before the template

For high-volume video rendering, a queue is not an implementation detail. It is the control surface that protects your source systems, API usage, review process, and retry logic.

The queue should know:

Which source record is being rendered.
Which template version created the payload.
Whether the job is waiting, submitted, active, completed, failed, or blocked.
How many retry attempts have happened.
Whether the failure came from input data, media availability, authentication, credits, rate limits, or an unexpected service error.

You do not need to submit every planned video at once. In many teams, the safer pattern is to submit a small window of jobs, poll those jobs, then submit more as capacity clears. That keeps the run observable and makes it easier to pause if the source data or template has a problem.

Build render payloads from structured data

Bulk rendering works when every variable part of the video is explicit. A product launch video might vary title, price, product image, brand color, disclaimer text, and CTA. A sales outreach video might vary company name, region, benefit copy, chart values, and logo URL. A learning platform might vary lesson title, step number, example screenshot, and outro link.

Before generating payloads, define a template contract:

Required fields that must exist before submission.
Optional fields with fallback copy or fallback visuals.
Text length limits for titles, captions, and CTAs.
Media URL checks for images, videos, GIFs, and audio.
Output settings such as aspect ratio, duration, frame rate, and format.
Naming rules for jobs and output files.

That contract is what turns bulk video generation from a fragile loop into a predictable automation workflow. If a record fails the contract, do not submit it. Mark it as blocked, show the missing fields, and let the data owner fix it.

Where AI video generation APIs fit

Many teams search for an AI video generation API when they need to generate videos from prompts, reference images, existing video assets, or text-to-video generation models. Those systems can be useful when the creative content itself needs to be generated. Bulk business video workflows often need a different layer: a repeatable video API that can assemble approved text, images, clips, captions, brand styles, aspect ratios, and CTAs into completed videos.

That distinction matters. A prompt can help create an idea, a voiceover, an image, a short video, or a storyboard. A JSON template controls how those assets appear in a consistent output. In a high-volume workflow, you may use AI models upstream to draft copy, summarize a product, choose a visual style, or generate reference images, then use Zvid to render the final structured video through API access.

For bulk rendering, focus less on one generation model and more on the workflow boundary:

What data creates each video?
Which assets are generated, approved, or pulled from an existing library?
Which template controls layout, duration, timing, and aspect ratio?
Which endpoint creates the render job?
Where do completed videos, previews, thumbnails, and failures get stored?

This keeps automation practical. Your team can improve prompts, templates, data cleanup, and review steps independently instead of treating video creation as one opaque request.

For example, a text prompt might create source copy, a video generation model might create a short clip, and an image-to-video tool might create motion from reference images. Those assets still need a production workflow: choose the right aspect ratio, place captions away from key visuals, add a CTA, create a preview, and store the completed video. Zvid fits after those creative steps when your application needs to turn approved inputs into consistent outputs for TikTok-style vertical clips, square social posts, landing page videos, or internal campaign variants.

Polling, retries, and failure handling

Zvid render jobs are asynchronous, so your application should treat the initial 202 response as the start of a workflow, not the final result. Save the returned jobId, then poll the job endpoint until the state is terminal.

For polling, use a steady interval and store the latest state. A simple implementation can poll every few seconds. A larger system can back off older jobs, prioritize recently submitted jobs, and stop polling after a failure or completion.

Retry rules should be narrow:

Retry temporary network errors around your own request.
Retry a job submission only if you know the first attempt did not create a job, or if you use a caller-side idempotency strategy.
Do not blindly retry validation failures. Fix the generated payload or source data.
Do not blindly retry missing media. Check whether the source URL is public, reachable, and intended for the render.
Store failed payloads so developers can reproduce and repair the issue.

Bulk rendering is strongest when repeatability, audit trails, and structured variation matter more than manual timeline editing.

The goal is not to hide every failure. The goal is to make failures inspectable. A good bulk pipeline lets someone answer whether the issue is bad input data, a broken media URL, an oversized text field, an expired API key, insufficient credits, or an orchestration bug.

Common mistakes

The most common mistake is trying to scale a one-off render script without adding state. Once you generate hundreds or thousands of videos, state is the product: source record state, payload state, job state, and delivery state.

Other mistakes include:

Submitting every render at once without a queue window.
Generating payloads from unvalidated source data.
Not storing the exact payload used for each render.
Reusing one layout across landscape, square, and portrait formats without checking text fit.
Polling forever after a job has reached a terminal state.
Retrying failures without classifying why they failed.
Losing the relationship between source record, job ID, and final video URL.
Treating media URLs as reliable without checking access and file type.
Updating a template during a run without recording the template version.
Shipping the first bulk run without reviewing a representative sample.

The fix is to make the workflow boring on purpose. Validate first, submit in controlled batches, poll consistently, store outcomes, and review a sample before increasing volume.

How to choose a bulk video generation API

The right bulk video generation API depends on whether your team needs generative video content, template-based video automation, or both. When evaluating AI video generator API options, separate creative generation from production rendering. A generative API may focus on prompts, reference images, image-to-video generation, text-to-video generation, or video extension. A template rendering API focuses on predictable output: the same layout, timing, aspect ratio, and brand rules applied across many source records.

For a high-volume workflow, evaluate the API around operations rather than demos:

Input model: Can your application send structured data, JSON templates, media URLs, and text variables, or does every request depend on a prompt?
Endpoint behavior: Does the API return a job ID for asynchronous rendering, and can your app poll or track completed videos?
Authentication: Can API key access be kept server-side, away from client UI code?
Output controls: Can you set duration, frame rate, output format, background color, layout, and aspect ratio for each render?
Template control: Can developers version the payload and reproduce the same video later?
Preview and review: Can your workflow store previews, thumbnails, failed payloads, and final URLs for human review?
Automation fit: Can it integrate with your CRM, CMS, product feed, spreadsheet, database, or internal application?

This is also where AI and deterministic rendering can work together. AI models can create short video clips, draft scripts, generate images, or suggest variants. Zvid can then assemble approved assets into a consistent final video through a JSON payload and render endpoint. That combination gives teams creative flexibility without giving up operational control.

Do not choose video generation APIs from a demo clip alone. For bulk production, run a small batch and compare source data quality, prompt reliability, template fit, generation speeds, preview review time, failure messages, and completed video storage. The best API for one-off AI videos may not be the best API to generate videos repeatedly from a database or product feed.

When to use Zvid

Use Zvid when your application needs repeatable server-side video rendering from structured JSON. It is a strong fit for e-commerce teams, agencies, marketing operations, AI video products, learning platforms, real estate workflows, internal enablement systems, and product-led growth teams that need many related video outputs.

One JSON render pipeline can power many repeatable video formats when the source data is structured.

Zvid is especially useful when you need:

One template rendered across many records.
Programmatic control over text, media, timing, layout, and output settings.
Hosted render jobs with API submission and polling.
A workflow that can be integrated into a CMS, CRM, product feed, internal tool, or automation platform.
Reviewable JSON payloads instead of hidden timeline edits.

If your team needs one handcrafted flagship video, a manual editor may be the better tool. If you need hundreds of product variants, personalized clips, localized videos, listing videos, onboarding snippets, or campaign creatives, a JSON-to-video API gives your engineering team a clearer system boundary.

Start with ten records, review the outputs, fix the template, then increase the queue window. Bulk video generation is easiest to scale after the template has already survived a small real batch.

FAQs

What is a bulk video generation API?

A bulk video generation API lets software create many videos from structured data by submitting render jobs programmatically instead of editing each video manually.

Is bulk video generation the same as text-to-video generation?

Not exactly. Text-to-video generation creates video content from a prompt, while bulk video generation usually maps structured records into repeatable templates and render jobs.

How do I generate 1,000 videos automatically?

Use a reusable video template, map each source record into a JSON payload, submit one render job per output, poll each job, and store the completed video URLs next to the source records.

Should I submit all 1,000 render jobs at once?

Usually no. A controlled queue window is easier to monitor, pause, and retry than a single burst of every planned job.

What should I store for each generated video?

Store the source record ID, template version, generated payload, render job ID, current state, failure reason if any, final video URL, and timestamps.

How do retries work in bulk video rendering?

Retry temporary request or network failures carefully, but do not blindly retry validation errors, bad media URLs, insufficient credits, or payload bugs.

Can I use product feeds or CSV files for bulk video generation?

Yes. Product feeds and CSV files are common sources because they already contain structured fields that can map into video titles, media, prices, CTAs, and styling.

Does every video need a different JSON payload?

Each output should have its own payload, but the payloads can come from one reusable template. The template stays stable while the data changes.

When is bulk rendering better than manual editing?

Bulk rendering is better when the videos share a repeatable structure and differ mostly by data, media, language, offer, audience, or format.

Can AI models be part of a bulk video workflow?

Yes. AI models can help draft copy, generate source visuals, summarize records, or suggest variants, while a JSON render template controls the final video structure.

What features matter in a bulk video generation API?

Look for server-side API access, asynchronous job status, structured template inputs, output controls, aspect ratio options, preview or thumbnail storage, and clear failure reporting.

AI B-roll Generator API: Automate with JSON

Mina Ramzy — Tue, 09 Jun 2026 21:00:00 +0000

To automate B-roll with JSON, represent each supporting clip, image, or graphic as a timed visual layer with a source URL, start time, end time, position, size, resize mode, and track order. In Zvid, those B-roll assets live in the same visuals array as titles, captions, overlays, and other scene elements, so your application can generate B-roll placement from scripts, product feeds, transcript cues, or editorial rules instead of editing every video by hand.

The core API flow is: build the JSON payload, submit it to POST https://api.zvid.io/api/render/api-key, then poll GET https://api.zvid.io/api/jobs/{id} until the render completes. Keep the JSON Structure overview, Image Elements reference, Video Elements reference, and Transitions reference nearby while you implement.

B-roll automation works best when editorial intent becomes structured timing data.

If you are new to Zvid's render model, start with How to Generate a Video from JSON, then compare this B-roll workflow with the broader JSON to Video API guide and the product-data pattern in How to Create Product Videos from a CSV or Product Feed.

Here is the public API loop most implementations need:

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @broll-render.json

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

The JSON model for automated B-roll

B-roll automation is a timeline problem. Your app needs to know which media asset should appear, when it should appear, how it should fit the frame, and whether it should sit behind or above the primary story layer.

In Zvid, each B-roll item can be modeled as a visual element:

IMAGE for product photos, screenshots, still frames, thumbnails, or generated graphics.
VIDEO for short supporting clips, demonstrations, background footage, or reaction shots.
GIF for lightweight animated accents.
SVG or TEXT for generated labels, callouts, diagrams, or timeline overlays.

The fields that matter most for B-roll are src, enterBegin, enterEnd, exitBegin, exitEnd, width, height, position, anchor, resize, track, opacity, and the optional animation or transition fields. The Submit render job reference documents the hosted render endpoint, and the Get render job status reference documents job polling after submission.

For example, a production B-roll image layer can look like this:

{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
  "width": 1280,
  "height": 720,
  "position": "center-center",
  "resize": "cover",
  "enterBegin": 2.2,
  "enterEnd": 2.6,
  "exitBegin": 5.8,
  "exitEnd": 6.2,
  "track": 2,
  "enterAnimation": "fade",
  "exitAnimation": "fade"
}

For a short supporting clip, use VIDEO with the same timeline fields and add source trimming when needed:

{
  "type": "VIDEO",
  "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
  "width": 1280,
  "height": 720,
  "position": "center-center",
  "resize": "cover",
  "videoBegin": 4,
  "videoEnd": 9,
  "enterBegin": 6,
  "exitEnd": 11,
  "volume": 0,
  "track": 2
}

Use volume: 0 when B-roll should not override narration, voiceover, or background music. If the B-roll clip should contribute audio, keep the volume intentional and test it against the rest of the mix.

Copy-paste Zvid B-roll timing payload

The renderable example below uses generated SVG panels to demonstrate B-roll timing without depending on any external media URL. In a production template, replace the SVG stand-ins with IMAGE, VIDEO, or GIF elements from your asset system while keeping the same timing and track ideas.

{
  "name": "automate-broll-json-demo",
  "resolution": "hd",
  "duration": 9,
  "frameRate": 30,
  "outputFormat": "mp4",
  "backgroundColor": "#0B1020",
  "visuals": [
    {
      "type": "SVG",
      "width": 1280,
      "height": 720,
      "track": 1,
      "svg": "<svg width='1280' height='720' viewBox='0 0 1280 720' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='bg' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#0B1020'/><stop offset='1' stop-color='#17233D'/></linearGradient><linearGradient id='accent' x1='0' y1='0' x2='1' y2='0'><stop offset='0' stop-color='#2DD4BF'/><stop offset='1' stop-color='#FADD46'/></linearGradient></defs><rect width='1280' height='720' fill='url(#bg)'/><rect x='64' y='46' width='1152' height='628' rx='30' fill='rgba(255,255,255,0.045)' stroke='rgba(255,255,255,0.13)'/><rect x='104' y='184' width='420' height='286' rx='28' fill='rgba(7,13,30,0.82)' stroke='rgba(255,255,255,0.12)'/><text x='136' y='234' fill='#FFFFFF' font-family='Arial' font-size='28' font-weight='800'>Primary story</text><rect x='136' y='270' width='318' height='18' rx='9' fill='rgba(255,255,255,0.18)'/><rect x='136' y='306' width='248' height='18' rx='9' fill='rgba(255,255,255,0.13)'/><rect x='136' y='342' width='286' height='18' rx='9' fill='rgba(255,255,255,0.13)'/><rect x='136' y='394' width='270' height='54' rx='18' fill='rgba(45,212,191,0.13)' stroke='rgba(45,212,191,0.38)'/><text x='271' y='428' text-anchor='middle' fill='#A7FFF6' font-family='Arial' font-size='18' font-weight='700'>script + narration</text><rect x='104' y='530' width='1072' height='74' rx='18' fill='rgba(0,0,0,0.28)' stroke='rgba(255,255,255,0.1)'/><line x1='152' y1='568' x2='1128' y2='568' stroke='rgba(255,255,255,0.23)' stroke-width='8' stroke-linecap='round'/><rect x='320' y='556' width='200' height='24' rx='12' fill='#2DD4BF'/><rect x='572' y='556' width='220' height='24' rx='12' fill='#FADD46'/><rect x='842' y='556' width='190' height='24' rx='12' fill='#A855F7'/><text x='640' y='644' text-anchor='middle' fill='#C8D2F1' font-family='Arial' font-size='18'>B-roll cues become timed visual layers</text></svg>"
    },
    {
      "type": "TEXT",
      "x": 640,
      "y": 112,
      "width": 1080,
      "anchor": "center-center",
      "track": 8,
      "enterBegin": 0.2,
      "enterEnd": 0.8,
      "enterAnimation": "fade",
      "exitBegin": 8.2,
      "exitEnd": 8.8,
      "exitAnimation": "fade",
      "html": "<div style='text-align:center; color:#ffffff; font-size:36px; font-weight:800; line-height:1.22;'>Automated B-roll from JSON timing</div>"
    },
    {
      "type": "SVG",
      "x": 662,
      "y": 214,
      "width": 430,
      "height": 235,
      "track": 4,
      "enterBegin": 1.1,
      "enterEnd": 1.6,
      "enterAnimation": "fade",
      "exitBegin": 3.1,
      "exitEnd": 3.5,
      "exitAnimation": "fade",
      "svg": "<svg width='430' height='235' viewBox='0 0 430 235' xmlns='http://www.w3.org/2000/svg'><rect width='430' height='235' rx='24' fill='#102A43'/><rect x='24' y='24' width='382' height='128' rx='20' fill='rgba(45,212,191,0.18)' stroke='rgba(45,212,191,0.55)'/><circle cx='94' cy='88' r='34' fill='#2DD4BF' opacity='0.9'/><rect x='154' y='62' width='170' height='18' rx='9' fill='rgba(255,255,255,0.76)'/><rect x='154' y='96' width='118' height='14' rx='7' fill='rgba(255,255,255,0.42)'/><text x='215' y='195' text-anchor='middle' fill='#FFFFFF' font-family='Arial' font-size='26' font-weight='800'>Product close-up</text></svg>"
    },
    {
      "type": "SVG",
      "x": 718,
      "y": 214,
      "width": 430,
      "height": 235,
      "track": 5,
      "enterBegin": 3.4,
      "enterEnd": 3.9,
      "enterAnimation": "fade",
      "exitBegin": 5.7,
      "exitEnd": 6.1,
      "exitAnimation": "fade",
      "svg": "<svg width='430' height='235' viewBox='0 0 430 235' xmlns='http://www.w3.org/2000/svg'><rect width='430' height='235' rx='24' fill='#2B1745'/><rect x='34' y='30' width='362' height='118' rx='20' fill='rgba(168,85,247,0.18)' stroke='rgba(168,85,247,0.58)'/><path d='M72 122 L148 66 L214 118 L270 82 L360 132' fill='none' stroke='#FADD46' stroke-width='10' stroke-linecap='round' stroke-linejoin='round'/><text x='215' y='195' text-anchor='middle' fill='#FFFFFF' font-family='Arial' font-size='26' font-weight='800'>Feature proof</text></svg>"
    },
    {
      "type": "SVG",
      "x": 662,
      "y": 214,
      "width": 430,
      "height": 235,
      "track": 6,
      "enterBegin": 6.0,
      "enterEnd": 6.5,
      "enterAnimation": "fade",
      "exitBegin": 8.1,
      "exitEnd": 8.6,
      "exitAnimation": "fade",
      "svg": "<svg width='430' height='235' viewBox='0 0 430 235' xmlns='http://www.w3.org/2000/svg'><rect width='430' height='235' rx='24' fill='#142B21'/><rect x='38' y='30' width='354' height='118' rx='20' fill='rgba(250,221,70,0.15)' stroke='rgba(250,221,70,0.6)'/><rect x='78' y='60' width='76' height='54' rx='12' fill='#FADD46' opacity='0.92'/><rect x='178' y='60' width='76' height='54' rx='12' fill='#2DD4BF' opacity='0.92'/><rect x='278' y='60' width='76' height='54' rx='12' fill='#FFFFFF' opacity='0.72'/><text x='215' y='195' text-anchor='middle' fill='#FFFFFF' font-family='Arial' font-size='26' font-weight='800'>Outcome shot</text></svg>"
    }
  ]
}

The payload visual is generated from the real renderable B-roll timing example.

For the public API request, wrap the project inside a top-level payload field:

{
  "payload": {
    "name": "automate-broll-json-demo",
    "resolution": "hd",
    "duration": 9,
    "frameRate": 30,
    "outputFormat": "mp4",
    "visuals": []
  }
}

How the B-roll workflow works

The most reliable B-roll automation systems separate editorial decisions from rendering. The renderer should receive clean timing data. It should not have to infer what the video is about.

Keep cue extraction, asset selection, JSON assembly, render submission, and job polling as separate steps.

A practical implementation usually looks like this:

Start with a script, transcript, product feed, tutorial outline, or campaign brief.
Extract cue windows such as product mention, feature proof, location, testimonial, screenshot, or outcome.
Match each cue to an approved media asset.
Convert each matched asset into an IMAGE, VIDEO, or GIF visual element.
Add timing, track order, resize behavior, and optional transitions.
Submit the payload to Zvid and poll the render job until the final video is ready.

This structure makes B-roll easier to review. Editors can approve cue timing and media choices before rendering. Developers can test one generated payload without opening a timeline editor. Marketers can reuse the same placement rules across many product videos, explainers, ads, or social clips.

Mapping B-roll plans from scripts or data

The input to your B-roll system can be human-written or machine-generated. The important part is to normalize it into a simple B-roll plan before you build the Zvid payload.

A readable CSV-style plan might look like this:

label,asset_url,asset_type,start_seconds,end_seconds,editor_note
product close-up,https://example.com/media/product-closeup.jpg,IMAGE,2.2,5.8,Show when the narration names the product
feature proof,https://example.com/media/dashboard-demo.mp4,VIDEO,6.0,11.0,Show dashboard evidence after the feature claim

This CSV is not the Zvid render payload. It is a review-friendly planning layer that editors, AI tools, or automation rules can produce before your application creates renderable JSON. When the plan is approved, your code maps each row into a Zvid visual element: asset_url becomes src, asset_type becomes type, start_seconds becomes enterBegin, and end_seconds becomes exitEnd. The template then adds layout fields such as width, height, position, resize, track, and optional animations.

For feed-driven content, the B-roll plan can be generated from the same data source that fills titles, prices, locations, or product attributes. That is why the CSV-to-video pattern maps well to B-roll: the data decides which supporting media appears, while the template controls where and how it appears.

Where AI video and B-roll footage fit

AI can help with B-roll automation, but it should feed the pipeline rather than replace the template. A prompt can ask an AI model to read a script, transcript, subtitle file, or product description and suggest cue windows such as "show dashboard," "show product close-up," "show customer outcome," or "show location context." Your app can then match those suggestions to approved stock footage, product media, image generation outputs, or an internal asset library.

That distinction matters for short-form videos, YouTube Shorts, Instagram Reels, tutorials, and product explainers. Content creators may want the speed of an AI B-roll generator, while teams still need predictable layout, caption safety, brand rules, and final video review. JSON is the handoff between the creative cue and the rendering API.

A useful AI-assisted pipeline looks like this:

Use AI or editorial rules to identify relevant B-roll footage windows.
Search an approved source such as an internal media library, Pexels-style stock footage, product screenshots, or generated images.
Convert the selected asset into a timed Zvid visual layer.
Render the final video through the API with a server-side API key.
Store the prompt, cue list, payload, and render job ID for review.

This keeps video production repeatable. If a generated cue is weak, you can improve the prompt or asset matcher. If the layout is weak, you can improve the JSON template. If the final video needs a different format, you can adjust the composition without changing the cue extraction step.

This is also where orchestration tools can sit around the render API. A team might use OpenAI for transcript analysis, a Pexels-style media search for stock footage, n8n or another workflow tool to move data between systems, and GitHub to version prompt and template changes. Zvid's role is the video creation step that turns the approved cue list into the final video through an API.

Prompt-only B-roll has limits. It may find a relevant topic but still choose the wrong shot, miss the original video pacing, place B-rolls over a caption, or produce a clip that feels generic instead of professional video. A video editor can catch those issues manually, but automation needs the same judgment encoded as reviewable data. Keep the cue list, prompt, selected asset URL, and JSON layer visible so reviewers can fix finding the right B-roll footage without rebuilding the whole video with AI.

Timing, tracks, resize, and transitions

B-roll quality depends less on how many clips you add and more on whether the timing and layout respect the viewer's attention.

B-roll layers need timing, layout, and track order, not just asset URLs.

Use these rules as a starting point:

Set enterBegin and exitEnd from the cue window.
Use enterEnd and exitBegin when you want a fade or other entrance and exit effect.
Use track so titles, captions, and callouts sit above B-roll when needed.
Use resize: "cover" for full-frame B-roll and resize: "contain" when the full asset must remain visible.
Use position, x, y, width, and height to create picture-in-picture or side-by-side layouts.
Use video transitions only between coordinated VIDEO elements when the handoff is intentional.

Do not turn every cue into a cutaway. B-roll is strongest when it clarifies the spoken point, shows proof, or adds visual context. Too much movement can make a generated video feel noisy even when every JSON field is valid.

For a talking-head explainer, B-roll often works well as short full-frame cutaways or picture-in-picture inserts. For product videos, it may be a sequence of product photos, feature screenshots, and outcome shots. For tutorials, it can be screen recordings or annotated UI steps. In each case, the JSON model stays the same: timed visual layers on a shared composition timeline.

API workflow for rendering B-roll

After your payload is ready, submit it through the Zvid render endpoint:

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @broll-render.json

Save the returned job ID, then poll the job endpoint:

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

Your application should treat rendering as asynchronous. Store the source cue list, the generated payload, the render job ID, and the final result URL together. That makes it much easier to debug a wrong asset, a mistimed cue, or a layout issue after the video has been generated.

If a render fails, inspect the payload your app sent rather than only checking the source data. The bug may be in the cue extractor, asset matcher, JSON mapper, or template. Keeping those stages separate makes automated B-roll easier to operate at scale.

Common mistakes

The biggest mistake is treating B-roll as a list of media URLs instead of a timeline. A URL alone does not define pacing, layout, layering, or audio behavior.

Other mistakes show up often:

Adding B-roll before the narration introduces the concept.
Letting cutaways hide important captions, titles, or product details.
Forgetting volume: 0 on supporting video clips when narration should stay dominant.
Using contain when the B-roll should fill the frame, or cover when the full screenshot must remain visible.
Putting every visual on the same track and getting unexpected layer order.
Creating transition chains before the basic timing is clear.
Using assets with inconsistent aspect ratios without testing the layout.
Generating cues from AI output without editorial review.
Forgetting that render jobs are asynchronous.
Reusing one B-roll template across portrait, square, and landscape formats without layout changes.

JSON-driven B-roll is strongest when placement rules are repeatable and reviewable.

The fix is to make B-roll part of the template contract. Define the allowed asset types, expected cue duration, track order, audio behavior, and layout variants before you generate hundreds of payloads.

When to use Zvid

Use Zvid when your application needs to generate videos from structured data and repeat the same B-roll logic across many outputs. It is a strong fit for agencies, AI video tools, ecommerce teams, tutorial platforms, internal enablement systems, and marketing operations teams that already know what supporting media should appear.

One cue system can power many video formats when B-roll is modeled as data.

Zvid is especially useful when you need:

Timed media layers generated from scripts, transcripts, feeds, or campaign rules.
Repeatable B-roll placement across many videos.
A JSON payload that controls scene layout, media, text, timing, and output settings.
A hosted API workflow for render submission and job polling.
Clear handoff between editorial cue review and automated rendering.

If your team only needs one carefully edited hero video, a manual editor may be the right tool. If you need product cutaways, tutorial inserts, social proof clips, or campaign variations generated repeatedly, JSON B-roll gives your app a better system boundary.

Start with one short cue list, map it into a Zvid payload, render the result, and inspect the timing before you scale the same template across more videos.

FAQs

What is automated B-roll?

Automated B-roll is supporting video, image, GIF, or graphic content placed on a timeline by software instead of manually edited clip by clip.

Can I add B-roll with JSON?

Yes. In Zvid, add B-roll as timed visual elements in the visuals array. Use IMAGE, VIDEO, GIF, SVG, or TEXT depending on the asset and layout.

Which fields control B-roll timing?

Use enterBegin, enterEnd, exitBegin, and exitEnd to control when each element appears and disappears on the timeline.

How do I keep B-roll from covering titles or captions?

Use track deliberately. Lower tracks render behind higher tracks, so keep background B-roll lower than titles, captions, and callouts.

Should B-roll video clips include audio?

Only when the source audio is part of the final story. For most narration-led workflows, set supporting video clips to volume: 0.

Can I use images instead of video clips for B-roll?

Yes. Product photos, screenshots, still frames, and generated graphics can work well as B-roll when they are timed and positioned correctly.

How do I choose between `cover` and `contain`?

Use cover when the asset should fill its frame and cropping is acceptable. Use contain when the entire asset must remain visible, such as UI screenshots or charts.

Can AI help choose B-roll cues?

Yes, AI can suggest cue windows from a script or transcript, but teams should still review cue quality, asset relevance, and timing before rendering.

Is B-roll automation useful for product videos?

Yes. Product feeds can map images, feature screenshots, benefit cards, and outcome shots into repeatable B-roll scenes.

Add Subtitles to Video with JSON: API Tutorial

Mina Ramzy — Tue, 09 Jun 2026 10:31:04 +0000

To add subtitles to a video with JSON, define caption segments with start, end, text, and words, add optional subtitle styles, then send the full video payload to a rendering API. In Zvid, subtitles live in the top-level subtitle object of the render payload, so captions can be generated, edited, versioned, translated, and rendered alongside the rest of the video scene.

The practical flow is simple: create the video layout, add timed caption data, submit the render job to POST https://api.zvid.io/api/render/api-key, and poll GET https://api.zvid.io/api/jobs/{id} until the captioned output is ready. If you start with an already recorded video or audio file, transcribe it upstream with a speech-to-text service, then convert that subtitle output into Zvid's captions and words structure before rendering. Keep the Subtitle reference, Caption reference, Word reference, and SubtitleStyles reference nearby while you implement.

Subtitles become easier to automate when transcript output becomes structured caption data.

If you are new to Zvid's overall render model, start with the JSON Structure overview, then compare this subtitle-focused workflow with How to Generate a Video from JSON and the broader JSON to Video API guide.

Here is the API loop most developers need:

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @captioned-render.json

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

The JSON subtitle model

Zvid subtitles are not a separate file upload in the common API pattern. They are part of the render payload. That makes them useful for applications that already produce transcripts, voiceover scripts, product narration, or short-form social captions as data.

The top-level subtitle object contains:

captions: an array of timed caption segments.
styles: optional typography, placement, and display mode settings.

Each caption segment contains:

start: when the caption appears, in seconds.
end: when the caption disappears, in seconds.
text: the full caption text for that segment.
words: an array of word-level timings.

Each word item contains start, end, and text. Word timings power interactive-looking subtitle modes such as one-word, karaoke, and progressive captions. They also make your data easier to inspect when a caption feels early, late, or hard to read.

This is different from uploading an external WebVTT, SRT, or closed captioning file after export. With Zvid, the caption text, timing metadata, font, position, and display mode can travel with the same JSON to video template that controls the visual scene. That gives your app full control over how subtitles appear in the final video, instead of merging captions manually in a separate editor.

Copy-paste Zvid caption payload

The example below renders a short captioned explainer card. The visual layout is intentionally simple so the subtitle data is the main thing to study.

{
  "name": "add-subtitles-json-demo",
  "resolution": "hd",
  "duration": 8,
  "frameRate": 30,
  "outputFormat": "mp4",
  "backgroundColor": "#101623",
  "visuals": [
    {
      "type": "SVG",
      "width": 1280,
      "height": 720,
      "svg": "<svg width='1280' height='720' viewBox='0 0 1280 720' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='bg' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#101623'/><stop offset='1' stop-color='#243047'/></linearGradient><linearGradient id='accent' x1='0' y1='0' x2='1' y2='0'><stop offset='0' stop-color='#2DD4BF'/><stop offset='1' stop-color='#FADD46'/></linearGradient></defs><rect width='1280' height='720' fill='url(#bg)'/><rect x='54' y='54' width='1172' height='612' rx='30' fill='rgba(255,255,255,0.045)' stroke='rgba(255,255,255,0.12)'/><rect x='96' y='92' width='186' height='38' rx='19' fill='rgba(45,212,191,0.14)' stroke='rgba(45,212,191,0.42)'/><text x='189' y='117' text-anchor='middle' fill='#A7FFF6' font-family='Arial' font-size='14' font-weight='700'>ZVID SUBTITLES</text><rect x='112' y='168' width='420' height='160' rx='24' fill='rgba(8,13,26,0.62)' stroke='rgba(255,255,255,0.12)'/><text x='152' y='215' fill='#FFFFFF' font-family='Arial' font-size='25' font-weight='800'>Caption data</text><text x='152' y='255' fill='#A7FFF6' font-family='Arial' font-size='18' font-weight='700'>{ start, end, text }</text><rect x='152' y='282' width='290' height='14' rx='7' fill='rgba(255,255,255,0.18)'/><rect x='152' y='308' width='224' height='14' rx='7' fill='rgba(255,255,255,0.13)'/><rect x='748' y='168' width='420' height='160' rx='24' fill='rgba(8,13,26,0.62)' stroke='rgba(255,255,255,0.12)'/><text x='788' y='215' fill='#FFFFFF' font-family='Arial' font-size='25' font-weight='800'>Rendered video</text><rect x='788' y='238' width='300' height='66' rx='18' fill='rgba(255,255,255,0.08)' stroke='rgba(255,255,255,0.13)'/><rect x='818' y='261' width='232' height='18' rx='9' fill='url(#accent)' opacity='0.9'/><rect x='818' y='288' width='190' height='11' rx='6' fill='rgba(255,255,255,0.18)'/><line x1='582' y1='252' x2='700' y2='252' stroke='#FADD46' stroke-width='7' stroke-linecap='round'/><polygon points='700,252 680,239 680,265' fill='#FADD46'/><text x='641' y='229' text-anchor='middle' fill='#FADD46' font-family='Arial' font-size='18' font-weight='700'>render</text></svg>"
    },
    {
      "type": "TEXT",
      "x": 640,
      "y": 116,
      "width": 840,
      "anchor": "center-center",
      "track": 4,
      "enterBegin": 0.2,
      "enterEnd": 0.8,
      "enterAnimation": "fade",
      "exitBegin": 7.2,
      "exitEnd": 7.7,
      "exitAnimation": "fade",
      "html": "<div style='text-align:center; color:#ffffff; font-size:40px; font-weight:800; line-height:1.12;'>JSON subtitles that render</div>"
    },
    {
      "type": "TEXT",
      "x": 640,
      "y": 566,
      "width": 920,
      "anchor": "center-center",
      "track": 5,
      "enterBegin": 0.6,
      "enterEnd": 1.1,
      "enterAnimation": "fade",
      "exitBegin": 7.1,
      "exitEnd": 7.6,
      "exitAnimation": "fade",
      "html": "<div style='text-align:center; color:#D7DEF6; font-size:24px; line-height:1.35;'>Keep captions, word timing, styles, and render output in one API payload.</div>"
    }
  ],
  "subtitle": {
    "captions": [
      {
        "start": 1,
        "end": 3.2,
        "text": "Build captions as JSON data",
        "words": [
          { "start": 1, "end": 1.45, "text": "Build" },
          { "start": 1.45, "end": 1.95, "text": "captions" },
          { "start": 1.95, "end": 2.3, "text": "as" },
          { "start": 2.3, "end": 2.75, "text": "JSON" },
          { "start": 2.75, "end": 3.2, "text": "data" }
        ]
      },
      {
        "start": 3.4,
        "end": 5.6,
        "text": "Control every word on the timeline",
        "words": [
          { "start": 3.4, "end": 3.8, "text": "Control" },
          { "start": 3.8, "end": 4.15, "text": "every" },
          { "start": 4.15, "end": 4.55, "text": "word" },
          { "start": 4.55, "end": 4.85, "text": "on" },
          { "start": 4.85, "end": 5.1, "text": "the" },
          { "start": 5.1, "end": 5.6, "text": "timeline" }
        ]
      },
      {
        "start": 5.8,
        "end": 7.4,
        "text": "Render the captioned video with Zvid",
        "words": [
          { "start": 5.8, "end": 6.1, "text": "Render" },
          { "start": 6.1, "end": 6.35, "text": "the" },
          { "start": 6.35, "end": 6.8, "text": "captioned" },
          { "start": 6.8, "end": 7.1, "text": "video" },
          { "start": 7.1, "end": 7.4, "text": "with Zvid" }
        ]
      }
    ],
    "styles": {
      "color": "#FFFFFF",
      "background": "#000000CC",
      "isBold": true,
      "fontSize": 42,
      "fontFamily": "Montserrat",
      "position": "center-center",
      "marginV": 0,
      "marginH": 0,
      "mode": "karaoke",
      "activeWord": {
        "color": "#FADD46"
      }
    }
  }
}

The payload visual is generated from the real renderable subtitle example in this tutorial.

For a public API request, wrap that project inside a top-level payload field:

{
  "payload": {
    "name": "add-subtitles-json-demo",
    "resolution": "hd",
    "duration": 8,
    "frameRate": 30,
    "outputFormat": "mp4",
    "visuals": [],
    "subtitle": {
      "captions": [
        {
          "start": 1,
          "end": 3.2,
          "text": "Build captions as JSON data",
          "words": [
            { "start": 1, "end": 1.45, "text": "Build" }
          ]
        }
      ]
    }
  }
}

How the subtitle workflow works

The workflow is easiest when you treat subtitle generation as a data pipeline, not as a manual editing step.

Keep transcript creation, subtitle format conversion, render submission, and job polling as separate steps.

A reliable implementation usually looks like this:

Generate or import a transcript from a speech-to-text service.
Convert the service output into Zvid caption segments with start, end, text, and words.
Preserve word-level timings from the transcription output where available.
Choose subtitle style settings for placement, color, background, and mode.
Add the subtitle object to the same payload that defines the video scene.
Submit the render job and poll for completion.

This separation matters because captions often need independent review. A designer may care about line length and placement. A localization team may care about translation quality. A developer may care about timestamp accuracy and retry behavior. JSON keeps those concerns explicit.

If an AI transcription service or speech-to-text tool creates the first draft, treat that output as source data rather than the final subtitle layer. Your app should map the provider's response into Zvid's subtitle format, including caption-level start, end, and text fields plus each caption's words array. Review proper nouns, numbers, speaker phrasing, punctuation, language, and line breaks before rendering.

Subtitle display modes and styles

Subtitle style settings control how the captions look and where they appear. Zvid supports common style fields such as color, background, fontSize, fontFamily, bold and italic flags, position, margins, display mode, and an activeWord color for word-aware modes.

A subtitle object combines text, timing, display mode, and style rules.

Use a solid or semi-transparent background when the underlying video is busy. Use center placement when the subtitle is the main teaching element, and move captions to the top or side when lower-third graphics, product details, or call-to-action buttons need that space.

For most API-driven workflows, start with one brand-safe caption preset:

{
  "styles": {
    "color": "#FFFFFF",
    "background": "#000000CC",
    "fontSize": 42,
    "fontFamily": "Montserrat",
    "isBold": true,
    "position": "center-center",
    "marginV": 0,
    "marginH": 0,
    "mode": "karaoke",
    "activeWord": {
      "color": "#FADD46"
    }
  }
}

Once that preset works, reuse it across templates. Change it only when the output channel, language, aspect ratio, or visual layout requires a different caption treatment.

For translated or localized subtitles, expect text length to change. A short English caption may become longer in another language, which can affect font size, line breaks, and position. Test the longest expected language before you generate subtitles automatically across many clips.

API workflow for rendering captions

After the payload is ready, submit it through the same render endpoint used for other Zvid videos. The Submit render job reference documents POST /api/render/api-key, and the Get render job status reference documents GET /api/jobs/{id}.

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @captioned-render.json

Save the returned job ID, then poll for status:

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

The important application behavior is to treat rendering as asynchronous. Submit the job, store the payload version, poll the job state, and only publish or notify the user after the completed result is available.

This is also where Zvid fits well with repeatable content systems. The same caption template can support social clips, onboarding videos, course snippets, translated product demos, and programmatic explainers. If the surrounding workflow starts from feeds or spreadsheet data, the pattern is similar to How to Create Product Videos from a CSV or Product Feed, except the dynamic fields include captions and word timings.

Adding subtitles to an existing video file

If your input is an already recorded video file, the JSON workflow still applies. Use a public media URL for the source video, add it as a VIDEO visual, then add the subtitle object with synchronized subtitles for the spoken audio. Zvid can create a video output with the captions rendered into the final frame.

Your app can automatically generate the first transcript with an AI or speech-to-text service, but the render payload should contain the reviewed result in Zvid's subtitle structure: clean text, caption segments, and word arrays that match the audio track. That is the difference between generating raw transcription and generating video subtitles that are readable in the finished clip.

For teams that need accessible video content, keep the source transcript and caption metadata even after export. The rendered subtitles help viewers watch the video, while a separate platform-specific caption file may still be useful when a publishing destination supports external accessibility tracks.

Common mistakes

The most common mistake is modeling subtitles as plain text instead of timed data. Plain transcript text is useful, but it does not tell the renderer when each caption should appear or how word-level modes should behave.

Other mistakes show up often:

Putting word timings outside the parent caption's time range.
Creating captions that are too long for the available screen time.
Using small font sizes on mobile-first outputs.
Leaving captions over important lower-third graphics.
Forgetting that render jobs are asynchronous.
Treating translated captions as a drop-in replacement without checking line length.
Using a busy video background without a readable caption background or outline.
Assuming automatic transcription is already perfect without editing the generated captions.
Confusing embedded visual subtitles with a separate accessibility caption file.
Forgetting to adjust subtitle animation, font size, or default placement for a new output format.

JSON-driven subtitles are strongest when captions are generated, reviewed, and rendered repeatedly.

The fix is to make the subtitle object part of your template contract. Store the caption data, the source transcript, the payload version, and the render job ID together. That makes subtitle bugs much easier to reproduce.

When to use Zvid

Use Zvid when your application needs to render captioned videos from structured data instead of manually editing every output. It is a strong fit for developer teams, short-form video tools, agencies, course platforms, ecommerce workflows, and automation systems that already know what the caption text should say.

Caption data can travel with the same JSON payload that controls the rest of the video.

Zvid is especially useful when you need:

Repeatable subtitle styling across many videos.
Timed captions generated from transcripts, scripts, or localization workflows.
Word-level subtitle modes for short-form videos.
A hosted API workflow for render submission and job polling.
One JSON payload that contains scene layout, media, captions, and output settings.

If your team only needs one hand-edited video, a manual editor may be enough. If you need captioned videos generated from product data, scripts, transcripts, lessons, or campaign templates, JSON subtitles are the better system boundary.

Start with one short payload, render it through Zvid, and inspect the subtitle output before you scale the same template across more videos.

FAQs

What fields are required for Zvid subtitles?

A subtitle object needs a captions array. Each caption needs start, end, text, and words. Each word needs start, end, and text.

Do I need word-level timings?

Yes, for Zvid subtitle captions that use the documented subtitle shape. Word timings are especially important for one-word, karaoke, and progressive display modes.

Can I style subtitles with JSON?

Yes. The styles object can define color, background, font size, font family, bold or italic text, placement, margins, display mode, and active word color.

Where does the subtitle object go?

Place subtitle at the top level of the Zvid render payload, alongside fields such as name, resolution, duration, frameRate, outputFormat, visuals, and audios.

Can I use subtitles with generated or feed-based videos?

Yes. Caption text and timing can be generated from transcripts, scripts, product data, localization workflows, or other structured inputs before you submit the render payload.

How should I validate subtitle JSON?

Check that every caption has start, end, text, and words, every word fits inside its parent caption, and the caption position does not cover important visual content.

How do I add subtitles to an already recorded video?

Transcribe the recorded audio first, convert the speech-to-text output into Zvid caption segments and word arrays, then add that subtitle object to the same Zvid payload that references the video or recreates the scene.

Can AI tools generate subtitles for this workflow?

Yes. AI transcription or speech-to-text tools can generate the first subtitle draft, but your app should still convert the result into Zvid's subtitle structure and review text accuracy, language, punctuation, and line length before sending the JSON payload to Zvid.

Are subtitles the same as closed captions?

Not always. In this article, subtitles are visual text rendered into the video. Closed captioning can also mean a separate accessibility track or file, depending on the publishing platform.

Product Video API: How APIs Power CSV Video Generation

Mina Ramzy — Fri, 05 Jun 2026 21:00:00 +0000

A product video API is one of the most practical video APIs for ecommerce teams because it lets you create videos from structured product data instead of editing every SKU by hand. To create product videos from a CSV or product feed, take each row of product data, map it into a reusable video layout, submit one REST API render payload per product, and poll the render jobs until the files are ready. That is the core pattern whether you are generating one launch video, one hundred catalog promos, or channel-specific variations for paid social and marketplaces.

The important shift is that your feed becomes the source of truth for video generation. Instead of rebuilding timelines manually, you define where the product title, price, CTA, brand colors, and product media should appear in a Zvid render payload. Once that mapping exists, you can render consistent product videos whenever your catalog changes. If you are new to the platform, start with the Getting Started guide, the Authentication guide, and the JSON Structure overview so your feed pipeline matches the public API model from the beginning.

A reusable product-video template turns feed rows into consistent campaign creative.

If you already have a feed export, the first working version can be simple. A CSV row with title, price, salePrice, cta, brandColor, backgroundColor, and productImageUrl is enough to generate a solid promo video when each field maps to a known place in the scene.

Here is the API shape most teams start with when they want to generate videos programmatically and on-demand:

export ZVID_API_BASE_URL=https://api.zvid.io

curl -X POST "$ZVID_API_BASE_URL/api/render/api-key" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZVID_API_KEY" \
  -d @render-job.json

Then poll the job until it completes:

curl "$ZVID_API_BASE_URL/api/jobs/$JOB_ID" \
  -H "x-api-key: $ZVID_API_KEY"

That flow is the same one described in the Getting Started guide. The difference for product feeds is how you generate render-job.json: you build it from structured catalog data instead of hand-authoring every scene.

Why feed-driven product video works

Feed-driven video works because product marketing is already structured. Your catalog already knows the product name, price, availability, category, promo language, and image URLs. The video layer should reuse that structure rather than forcing your team to recreate it in an editor for every SKU.

This approach is especially useful when you need:

One branded template for many products
Fast refreshes for sales, pricing, and inventory changes
Different aspect ratios for paid social, marketplace ads, and PDP video slots
Consistent CTA placement and visual hierarchy across the whole catalog

It is also easier to maintain. Your engineering or automation team can version the mapping logic, while marketing keeps control over the copy fields and brand rules that live in the feed itself.

Product video API workflow

The cleanest video workflow is: ingest feed rows, normalize the fields, map each row to a Zvid payload, submit render jobs through the endpoint, and save the resulting video URL or CDN URL back to your CMS, PIM, Shopify catalog, or ad pipeline. This is the practical difference between a one-off video editing project and video automation that can run every time product details change.

A product-feed pipeline separates data cleanup, template mapping, and rendering into repeatable steps.

In practice, the product video API pipeline looks like this:

Parse the CSV or pull the product feed from your source system.
Normalize fields so your template logic gets predictable values.
Map each normalized row to scene text, colors, media, and timing.
Submit one render job per video variation through the API.
Poll job status and store the completed video URL where the business needs it.

If you want to use real product photos in production, the Image Elements reference shows how remote image sources work, while the Text Elements reference explains the text layer behavior you will use for titles, prices, and CTAs.

What is a product video API for video creation?

A product video API is a creation API for rendering product videos from structured inputs such as product details, image URLs, prices, badges, and calls to action. Unlike a hosting API from a platform such as Vimeo, or live streaming and transcoding APIs for uploaded media, a product video API generates new product video content from a payload.

For ecommerce teams, the key use case is repeatable video production at scale. Developers send one API call per output, track the job state, and store the finished video URL. That makes it possible to create videos for TikTok ads, marketplace listings, PDP modules, short-form explainers, thumbnails, GIFs, and localized campaign variants without rebuilding the same timeline in a UI.

REST API pipeline and API key setup

A reliable REST API implementation keeps auth, payload creation, rendering, and storage separate. First, keep your API key in server-side configuration. Next, build a payload from the product row. Then send it via API to the render endpoint and save the returned job identifier. When the job completes, write the final URL back to your product system.

That single API loop is small enough to test in a few lines of code, but it can expand into high-volume automated workflows with webhooks, retries, queue monitoring, and per render cost controls. Zvid focuses on rendering videos from templates and structured JSON rather than text prompts, avatar generation, native audio synthesis, or image-to-video generation.

Map feed columns into a reusable Zvid template

The template is the durable asset. The feed row is the changing input.

For example, a row like this:

{
  "sku": "BAG-204",
  "title": "Transit Weekender Bag",
  "price": "$129",
  "salePrice": "$99",
  "cta": "Shop the drop",
  "brandColor": "#5B3DF5",
  "accentColor": "#F5C94A",
  "productImageUrl": "https://cdn.example.com/products/transit-weekender-bag.jpg"
}

can be mapped into a render payload with a function like this:

function buildRenderJob(row) {
  return {
    payload: {
      name: `product-video-${row.sku}`,
      resolution: "instagram-story",
      duration: 10,
      frameRate: 30,
      outputFormat: "mp4",
      backgroundColor: "#0D1020",
      visuals: [
        {
          type: "IMAGE",
          src: row.productImageUrl,
          x: 260,
          y: 960,
          width: 520,
          height: 760,
          anchor: "center-center",
          resize: "contain"
        },
        {
          type: "TEXT",
          x: 760,
          y: 520,
          width: 520,
          anchor: "center-center",
          html: `<div style='text-align:left; color:#ffffff; font-size:64px; font-weight:700; line-height:1.08;'>${row.title}</div>`
        },
        {
          type: "TEXT",
          x: 760,
          y: 860,
          width: 520,
          anchor: "center-center",
          html: `<div style='text-align:left; color:${row.accentColor}; font-size:58px; font-weight:700;'>${row.salePrice || row.price}</div>`
        }
      ]
    }
  };
}

The idea is not to hard-code one product. It is to define a stable scene system and let the feed swap in the product-specific values. That becomes much easier when your payload structure follows the public docs for resolution presets, text layers, and image layers.

A feed-driven template works when every incoming field has a fixed role in the scene.

Example Zvid API payload for one product video

Below is a proof-friendly example payload for a single product promo. It uses SVG and TEXT elements only so you can study the scene structure clearly. In a production feed pipeline, you would usually replace the illustrated product card with a real remote product image or video clip.

{
  "name": "product-feed-demo-bag",
  "resolution": "hd",
  "duration": 10,
  "frameRate": 30,
  "outputFormat": "mp4",
  "backgroundColor": "#0d1020",
  "visuals": [
    {
      "type": "SVG",
      "width": 1280,
      "height": 720,
      "svg": "<svg width='1280' height='720' viewBox='0 0 1280 720' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='bg' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#0d1020'/><stop offset='1' stop-color='#1f153d'/></linearGradient><radialGradient id='glowA' cx='0' cy='0' r='1' gradientUnits='userSpaceOnUse' gradientTransform='translate(1060 120) rotate(90) scale(260)'><stop stop-color='#5b3df5' stop-opacity='0.30'/><stop offset='1' stop-color='#5b3df5' stop-opacity='0'/></radialGradient><radialGradient id='glowB' cx='0' cy='0' r='1' gradientUnits='userSpaceOnUse' gradientTransform='translate(220 620) rotate(90) scale(280)'><stop stop-color='#f5c94a' stop-opacity='0.20'/><stop offset='1' stop-color='#f5c94a' stop-opacity='0'/></radialGradient></defs><rect width='1280' height='720' fill='url(#bg)'/><circle cx='1060' cy='120' r='260' fill='url(#glowA)'/><circle cx='220' cy='620' r='280' fill='url(#glowB)'/><rect x='32' y='32' width='1216' height='656' rx='34' fill='rgba(255,255,255,0.035)' stroke='rgba(255,255,255,0.08)'/></svg>"
    },
    {
      "type": "SVG",
      "x": 330,
      "y": 370,
      "width": 420,
      "height": 520,
      "anchor": "center-center",
      "track": 3,
      "enterBegin": 0.2,
      "enterEnd": 0.9,
      "enterAnimation": "smoothleft",
      "exitBegin": 9.2,
      "exitEnd": 9.8,
      "exitAnimation": "fade",
      "svg": "<svg width='420' height='520' viewBox='0 0 420 520' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='card' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='rgba(255,255,255,0.12)'/><stop offset='1' stop-color='rgba(255,255,255,0.05)'/></linearGradient><linearGradient id='bag' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#6f58ff'/><stop offset='1' stop-color='#f5c94a'/></linearGradient></defs><rect x='0.5' y='0.5' width='419' height='519' rx='32' fill='url(#card)' stroke='rgba(255,255,255,0.14)'/><rect x='36' y='34' width='126' height='34' rx='17' fill='rgba(245,201,74,0.14)' stroke='rgba(245,201,74,0.34)'/><text x='99' y='56' text-anchor='middle' fill='#f5c94a' font-size='15' font-family='Inter' font-weight='700'>NEW ARRIVAL</text><rect x='78' y='108' width='264' height='272' rx='28' fill='rgba(10,16,31,0.40)' stroke='rgba(255,255,255,0.10)'/><path d='M150 198 C150 160 178 138 210 138 C242 138 270 160 270 198' fill='none' stroke='url(#bag)' stroke-width='18' stroke-linecap='round'/><rect x='126' y='188' width='168' height='150' rx='34' fill='url(#bag)'/><rect x='156' y='224' width='108' height='18' rx='9' fill='rgba(255,255,255,0.22)'/><rect x='106' y='408' width='208' height='20' rx='10' fill='rgba(255,255,255,0.11)'/><rect x='132' y='442' width='156' height='16' rx='8' fill='rgba(245,201,74,0.18)'/></svg>"
    },
    {
      "type": "TEXT",
      "x": 852,
      "y": 148,
      "width": 520,
      "anchor": "center-center",
      "track": 8,
      "enterBegin": 0.4,
      "enterEnd": 1,
      "enterAnimation": "fade",
      "exitBegin": 9.1,
      "exitEnd": 9.7,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; color:#f5c94a; font-size:18px; font-weight:700; letter-spacing:1px;'>WEEKEND TRAVEL ESSENTIAL</div>"
    },
    {
      "type": "TEXT",
      "x": 852,
      "y": 268,
      "width": 520,
      "anchor": "center-center",
      "track": 10,
      "enterBegin": 0.6,
      "enterEnd": 1.3,
      "enterAnimation": "fade",
      "exitBegin": 9,
      "exitEnd": 9.6,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; color:#ffffff; font-family:Poppins; font-size:54px; font-weight:700; line-height:1.08;'>Transit Weekender Bag</div>"
    },
    {
      "type": "TEXT",
      "x": 852,
      "y": 404,
      "width": 520,
      "anchor": "center-center",
      "track": 9,
      "enterBegin": 0.9,
      "enterEnd": 1.5,
      "enterAnimation": "fade",
      "exitBegin": 8.9,
      "exitEnd": 9.5,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; line-height:1.3;'><div style='color:#9ea7d8; font-size:22px; margin-bottom:10px;'>Carry-on sized. Structured silhouette. Limited seasonal colorway.</div><div style='color:#f5c94a; font-size:52px; font-weight:700;'>$99 <span style='color:#8a92bf; font-size:24px; text-decoration:line-through;'>$129</span></div></div>"
    },
    {
      "type": "TEXT",
      "x": 852,
      "y": 534,
      "width": 420,
      "anchor": "center-center",
      "track": 8,
      "enterBegin": 1.2,
      "enterEnd": 1.8,
      "enterAnimation": "fade",
      "exitBegin": 8.8,
      "exitEnd": 9.4,
      "exitAnimation": "fade",
      "html": "<div style='display:inline-block; background:rgba(91,61,245,0.20); border:1px solid rgba(91,61,245,0.42); border-radius:26px; padding:16px 24px; color:#ffffff; font-size:22px; font-weight:700;'>Shop the drop</div>"
    },
    {
      "type": "TEXT",
      "x": 640,
      "y": 654,
      "width": 1080,
      "anchor": "center-center",
      "track": 6,
      "enterBegin": 1.4,
      "enterEnd": 2,
      "enterAnimation": "fade",
      "exitBegin": 8.7,
      "exitEnd": 9.3,
      "exitAnimation": "fade",
      "html": "<div style='text-align:center; color:#c4c9ea; font-size:16px;'>Mapped from feed fields: title, list price, sale price, badge, CTA, and brand colors.</div>"
    }
  ]
}

The same payload structure can be reused for every row in your catalog.

This is also a good place for a mid-funnel CTA: if your team already has product data in a spreadsheet, feed, or database table, test one product row first. Build a single reusable template, send one render job, confirm the layout, and then scale from there.

Video editing vs feed-driven rendering

The decision is mostly about volume and repeatability.

Manual editing is fine when you need a handful of one-off launch videos.
Feed-driven rendering is better when the creative structure stays mostly the same while the product data changes often.
A template plus API flow gives engineering teams a way to control consistency, retries, and output destinations.
A feed-driven system also makes localization and promotion-specific variants much easier because the text and pricing already live in structured fields.

Product feeds outperform manual editing when the scene stays stable and the data changes often.

Video generation API use case checklist

When you compare video APIs, look for the part of the workflow each platform actually owns. Some APIs are built for upload, playback, live streams, and cloud infrastructure. Others are AI video generator tools for text to video, image generation, or prompt-based creative output. For feed-driven ecommerce, you usually need a video generation API that is fully customizable, accepts product data programmatically, supports videos using real product URLs, and returns a finished asset your app can store.

A practical checklist is:

Can the API generate videos from product details without manual video editing?
Can one API call create a predictable render from a saved layout?
Does the endpoint support image URLs, text layers, brand colors, and output presets?
Can the pipeline support high-volume catalog refreshes and automated workflows?
Can the result be routed to a CDN, ad platform, CMS, or Shopify workflow?

AI video generator, no-code, and ecommerce integrations

Developers often start with direct API calls, then connect the same workflow to no-code tools when marketing or operations teams need control. A product feed pipeline can be triggered from n8n, Zapier, a Shopify export, a PIM change, or a scheduled catalog job. Tools such as Creatomate, HeyGen, and ElevenLabs solve adjacent creation problems, but the right product video API depends on whether you need configurable product layouts, AI features, text prompts, avatar clips, or structured rendering from CSV data.

Zvid fits the structured rendering side: define the layout, inject feed values, render the asset, and send the completed video directly to the destination that needs it.

Common mistakes

The most common failure is trying to automate before the template rules are clear. If the title box, price placement, offer badge, and CTA style are still changing every day, the feed mapping will stay unstable.

Other mistakes show up repeatedly:

Treating the CSV as clean input when fields actually need normalization first
Letting title length vary wildly without defining truncation or line-break rules
Mixing channel formats without deciding when to use instagram-story, instagram-post, youtube-video, or another supported preset
Hard-coding promotional copy in the template instead of sourcing it from the feed
Using a template that depends on manual visual tweaks for every product

Before scaling, decide which fields are required, which are optional, and what the fallback behavior should be when an image, sale price, or CTA is missing.

When to use Zvid for video automation

Zvid makes sense when you want the video itself to be a programmatic output of your product data.

Use Zvid when you need:

Reusable scene templates for many products or offers
API-based render submission and job polling in your own pipeline
Flexible control over text, layout, timing, and media placement
Different outputs for paid social, lifecycle campaigns, marketplaces, or storefronts

Do not over-engineer it for a tiny catalog with rare changes. The advantage appears when you want a repeatable system rather than a one-time edit.

One shared feed can power storefront, paid social, and marketplace video variants.

For implementation detail, the most useful internal docs to keep open are the JSON Structure overview, Text Elements reference, Image Elements reference, and Resolution Presets reference. Those pages define the scene building blocks you will reuse as your catalog grows.

If you want to prove the workflow quickly, start with one row, one template, and one destination format. After that, add batch submission, channel variants, and post-render routing back into your commerce stack.

FAQs

Which type of video API do I need?

If you need to host or stream uploaded files, choose a hosting or live streaming API. If you need text-to-video or image-to-video generation from prompts, choose an AI video generator API. If you need to generate product videos from catalog data, choose a product video API that accepts structured fields, images, and layout rules.

Can I automate video creation with a video API?

Yes. A video API can automate video creation when your application can build the payload, call the endpoint, poll for completion, and store the result URL. The strongest use case is a repeatable layout with changing inputs.

Can I create many videos from one CSV file?

Yes. The usual pattern is to parse the CSV into rows, map each row into a render payload, and submit one API job per output. The template stays stable while the product fields change.

Do I need a different template for every product category?

Not always. Many teams start with one universal promo template and then split into category-specific templates only when aspect ratios, copy density, or media framing diverge too much.

Does this work with Meta, Google, TikTok, and other ad platforms?

Yes, if your pipeline renders the right aspect ratio and stores the finished video URL where your ad or product workflow can access it. For example, one feed can produce vertical TikTok variants, square marketplace assets, and landscape product explainers.

Can I use real product images instead of illustrated placeholders?

Yes. In production, you would normally use remote image URLs with Zvid's Image Elements. The example payload here keeps the scene self-contained so the structure is easier to study and adapt.

Structured product data is already most of the work. The leverage comes from turning that structure into a reusable video template and a reliable render workflow. If that matches your use case, test one product row with Zvid, confirm the layout, and then scale the same template across the rest of your feed.

Generate Video from JSON: AI Context and API Workflow

Mina Ramzy — Thu, 04 Jun 2026 21:00:00 +0000

To generate video from JSON, define the video as structured data, send that payload to a rendering API, save the returned job ID, and poll the job until the final video URL is ready. That is the practical JSON to video workflow behind most JSON video generators: your application creates the scene definition, and the renderer turns it into a finished file.

With Zvid, that flow is public and straightforward. You verify your API key, submit a payload to POST https://api.zvid.io/api/render/api-key, then poll GET https://api.zvid.io/api/jobs/{id} until the render completes. The best reference pages to keep open while you implement it are the Getting Started guide, the Authentication guide, the JSON Structure overview, and the published deep dive JSON to Video API: Convert JSON to Video with Zvid.

Structured JSON becomes a repeatable render workflow when the payload shape stays stable.

If you want to see the broader feed-driven pattern after this tutorial, the same ideas also show up in How to Create Product Videos from a CSV or Product Feed. The difference here is that we are starting with one payload and one render job instead of a larger automation pipeline.

Here is the minimal public API sequence most developers start with:

curl -X GET https://api.zvid.io/api/user/profile \
  -H "x-api-key: YOUR_API_KEY"

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @render-job.json

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

What it means to generate a video from JSON

Generating a video from JSON means your timeline is described as data instead of being trapped inside a manual editor file.

That JSON can define the canvas size, video duration, frame rate, background color, text layers, images, videos, audio tracks, subtitle timing, and output format. Zvid then validates the payload, queues the job, renders the composition, and returns the result when the job is done.

This is useful when:

The same video layout needs many content variations.
Your app already stores the inputs as structured data.
You want repeatable renders instead of one-off exports.
You need a server-side workflow that can submit, retry, and track jobs predictably.

If you only need one handcrafted launch video, a manual editor may still be faster. If your product already thinks in structured inputs, JSON rendering is usually a much better fit.

How the JSON to video workflow works

The working loop is: build the JSON payload, submit the job, poll the result, then store or publish the finished video URL. In other words, the JSON file or JSON object acts like a video template plus the values that should fill it.

Keep payload generation, submission, and job polling as separate steps.

In practice, the flow looks like this:

Build one valid Zvid payload object.
Submit that payload to POST https://api.zvid.io/api/render/api-key.
Save the returned jobId, status, and queue details.
Poll GET https://api.zvid.io/api/jobs/{id} until the state is completed or failed.
Use result.url when the render finishes.

The Submit render job reference is the canonical source for the request body, and the Get render job status reference is the canonical source for the polling response shape.

If you are evaluating the workflow for the first time, the right CTA is simple: copy one payload, submit one render, and verify one finished result before you design anything more ambitious.

Copy-paste Zvid JSON example

The render request body must contain a top-level payload. Inside that payload, the main fields are name, resolution, duration, frameRate, outputFormat, backgroundColor, visuals, audios, and subtitle, as described in the JSON Structure overview, the Resolution Presets reference, and the Text Elements reference.

Below is a proof-friendly Zvid API payload for a short tutorial-style explainer card. It uses SVG and TEXT elements only so the layout is easy to study and adapt.

{
  "name": "generate-video-from-json-demo",
  "resolution": "hd",
  "duration": 8,
  "frameRate": 30,
  "outputFormat": "mp4",
  "backgroundColor": "#0b1020",
  "visuals": [
    {
      "type": "SVG",
      "width": 1280,
      "height": 720,
      "svg": "<svg width='1280' height='720' viewBox='0 0 1280 720' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='bg' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#0b1020'/><stop offset='1' stop-color='#1b2147'/></linearGradient><radialGradient id='glowA' cx='0' cy='0' r='1' gradientUnits='userSpaceOnUse' gradientTransform='translate(1080 110) rotate(90) scale(250)'><stop stop-color='#2dd4bf' stop-opacity='0.18'/><stop offset='1' stop-color='#2dd4bf' stop-opacity='0'/></radialGradient><radialGradient id='glowB' cx='0' cy='0' r='1' gradientUnits='userSpaceOnUse' gradientTransform='translate(210 640) rotate(90) scale(260)'><stop stop-color='#f6b84d' stop-opacity='0.16'/><stop offset='1' stop-color='#f6b84d' stop-opacity='0'/></radialGradient></defs><rect width='1280' height='720' fill='url(#bg)'/><circle cx='1080' cy='110' r='250' fill='url(#glowA)'/><circle cx='210' cy='640' r='260' fill='url(#glowB)'/><rect x='30' y='30' width='1220' height='660' rx='34' fill='rgba(255,255,255,0.035)' stroke='rgba(255,255,255,0.08)'/></svg>"
    },
    {
      "type": "SVG",
      "x": 304,
      "y": 368,
      "width": 416,
      "height": 470,
      "anchor": "center-center",
      "track": 2,
      "enterBegin": 0.2,
      "enterEnd": 0.8,
      "enterAnimation": "smoothleft",
      "exitBegin": 7.1,
      "exitEnd": 7.7,
      "exitAnimation": "fade",
      "svg": "<svg width='416' height='470' viewBox='0 0 416 470' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='card' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='rgba(255,255,255,0.13)'/><stop offset='1' stop-color='rgba(255,255,255,0.05)'/></linearGradient><linearGradient id='panel' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#2dd4bf'/><stop offset='1' stop-color='#4f73ff'/></linearGradient></defs><rect x='0.5' y='0.5' width='415' height='469' rx='30' fill='url(#card)' stroke='rgba(255,255,255,0.14)'/><rect x='30' y='30' width='138' height='32' rx='16' fill='rgba(45,212,191,0.14)' stroke='rgba(45,212,191,0.34)'/><text x='99' y='51' text-anchor='middle' fill='#9ef3ea' font-size='14' font-family='Arial' font-weight='700'>JSON PAYLOAD</text><rect x='30' y='90' width='356' height='134' rx='22' fill='rgba(9,16,31,0.58)' stroke='rgba(255,255,255,0.08)'/><rect x='30' y='244' width='356' height='82' rx='22' fill='rgba(9,16,31,0.58)' stroke='rgba(255,255,255,0.08)'/><rect x='30' y='346' width='356' height='92' rx='22' fill='url(#panel)' opacity='0.92'/><rect x='58' y='118' width='136' height='16' rx='8' fill='rgba(255,255,255,0.24)'/><rect x='58' y='148' width='236' height='13' rx='6.5' fill='rgba(255,255,255,0.10)'/><rect x='58' y='174' width='194' height='13' rx='6.5' fill='rgba(255,255,255,0.10)'/><rect x='58' y='270' width='122' height='14' rx='7' fill='rgba(255,255,255,0.22)'/><rect x='58' y='296' width='232' height='12' rx='6' fill='rgba(255,255,255,0.10)'/><rect x='58' y='374' width='194' height='18' rx='9' fill='rgba(255,255,255,0.28)'/><rect x='58' y='404' width='132' height='12' rx='6' fill='rgba(255,255,255,0.18)'/></svg>"
    },
    {
      "type": "TEXT",
      "x": 874,
      "y": 146,
      "width": 500,
      "anchor": "center-center",
      "track": 6,
      "enterBegin": 0.4,
      "enterEnd": 1,
      "enterAnimation": "fade",
      "exitBegin": 7,
      "exitEnd": 7.6,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; color:#9ef3ea; font-size:18px; font-weight:700; letter-spacing:1px;'>FROM JSON TO RENDERED VIDEO</div>"
    },
    {
      "type": "TEXT",
      "x": 874,
      "y": 270,
      "width": 500,
      "anchor": "center-center",
      "track": 8,
      "enterBegin": 0.6,
      "enterEnd": 1.3,
      "enterAnimation": "fade",
      "exitBegin": 6.9,
      "exitEnd": 7.5,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; color:#ffffff; font-size:50px; font-weight:700; line-height:1.1;'>Define one scene in JSON, then let the API render it.</div>"
    },
    {
      "type": "TEXT",
      "x": 874,
      "y": 420,
      "width": 500,
      "anchor": "center-center",
      "track": 8,
      "enterBegin": 0.9,
      "enterEnd": 1.5,
      "enterAnimation": "fade",
      "exitBegin": 6.8,
      "exitEnd": 7.4,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; color:#d7def6; font-size:22px; line-height:1.45;'>Use the same payload pattern for demos, explainers, feed-driven videos, and automated campaign variations.</div>"
    },
    {
      "type": "TEXT",
      "x": 820,
      "y": 556,
      "width": 340,
      "anchor": "center-center",
      "track": 9,
      "enterBegin": 1.1,
      "enterEnd": 1.7,
      "enterAnimation": "fade",
      "exitBegin": 6.7,
      "exitEnd": 7.3,
      "exitAnimation": "fade",
      "html": "<div style='display:inline-block; background:rgba(246,184,77,0.20); border:1px solid rgba(246,184,77,0.42); border-radius:24px; padding:16px 24px; color:#ffffff; font-size:22px; font-weight:700;'>Submit your first job</div>"
    },
    {
      "type": "TEXT",
      "x": 640,
      "y": 654,
      "width": 1080,
      "anchor": "center-center",
      "track": 4,
      "enterBegin": 1.3,
      "enterEnd": 1.9,
      "enterAnimation": "fade",
      "exitBegin": 6.6,
      "exitEnd": 7.2,
      "exitAnimation": "fade",
      "html": "<div style='text-align:center; color:#c4cceb; font-size:16px;'>Start small: one payload, one job, one finished output.</div>"
    }
  ]
}

The payload stays reusable when each field has one clear job in the render.

The point of this example is not the design. It is the shape of the request. Once your app can build one valid payload consistently, generating videos from JSON becomes a normal systems problem instead of a manual export task.

If you want remote media instead of an all-SVG tutorial card, the Text Elements reference explains safe text and HTML rendering, while the JSON Structure overview shows where images, videos, audio, and subtitles fit into the same payload model.

Send the render job and poll status

Once the payload shape makes sense, the rest is standard API work.

Start by verifying authentication:

curl -X GET https://api.zvid.io/api/user/profile \
  -H "x-api-key: YOUR_API_KEY"

Then submit a render request:

{
  "payload": {
    "name": "generate-video-from-json-demo",
    "resolution": "hd",
    "duration": 8,
    "frameRate": 30,
    "outputFormat": "mp4",
    "backgroundColor": "#0b1020",
    "visuals": [
      {
        "type": "TEXT",
        "text": "Hello from Zvid",
        "x": 640,
        "y": 360,
        "anchor": "center-center",
        "style": {
          "fontSize": 54,
          "color": "#ffffff",
          "textAlign": "center"
        }
      }
    ]
  }
}

Then poll the job:

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

The Getting Started guide shows the same sequence with response examples, and the Get render job status reference shows the fields you should expect in the poll response. Save the returned jobId, track the job state, and only treat the render as done when the API returns a completed result.

This is the second CTA most readers need: do not build a full queueing system first. Submit one valid payload, inspect one finished output, and then scale the workflow once the basic loop is solid.

JSON prompt vs structured render payload

Search results for JSON video generation often mix two related ideas: a JSON prompt for an AI video generator and a structured JSON payload for a video rendering API. They both use JSON, but they are not the same workflow.

A JSON prompt for AI video generation usually describes creative intent for a model such as Sora, Veo, Google Veo 3, Veo 3.1, or Seedance. It may include camera motion, subject, lighting, style, dialogue, negative prompts, video length, and other prompt structure details. That can be useful when you want an AI-generated scene from text prompts or image generation inputs.

A Zvid render payload is more deterministic. It describes the output video as a set of explicit fields: resolution, duration, frame rate, visuals, text, media URLs, timing, subtitles, and output format. That makes it better when you need consistent video production, on-brand layouts, product data, placeholders for text, and repeatable video rendering without manual editing.

Use the AI prompt approach when the model should invent the shot. Use a structured render payload when your application already knows the content and needs to programmatically generate a video from structured JSON data.

JSON templates for video automation

A good JSON template separates stable design rules from dynamic content. The template might define the layout, animation timing, colors, subtitle placement, and output format. Your application can then inject the values that change, such as headline, CTA, product image, voiceover file, locale, or campaign name.

That structure is what lets teams automate video creation instead of editing every output by hand. You can create a template once, validate it with a small payload, and then use the same JSON format to generate videos automatically for many variants.

A practical template checklist:

Keep required fields predictable, including name, resolution, duration, frameRate, and outputFormat.
Define placeholders for text, media URLs, subtitles, and optional campaign fields.
Decide fallback behavior for missing images, long titles, unsupported formats, and empty CTA text.
Keep scene layout logic separate from product, marketing, CRM, or spreadsheet data.
Save the payload version so you can debug and regenerate the same video later.

JSON rendering vs manual editing

The practical tradeoff is repeatability versus handcrafted flexibility.

Manual editing is better when every video needs one-off creative work.
JSON rendering is better when the structure repeats and the inputs change.
Manual editors optimize for human timeline work.
JSON payloads optimize for systems that can generate many variations reliably.

JSON rendering wins when the scene repeats and the data changes.

That is why JSON-driven rendering is common in catalog automation, localized campaign variants, onboarding sequences, personalized clips, and app-generated explainers. The same template logic can keep paying off long after the first demo works.

Use cases and integrations

The strongest use case for a JSON to video workflow is repeatable output from structured data. That can include product videos, personalized videos, onboarding explainers, video marketing assets, social media content for TikTok or other channels, internal training clips, and automated status updates.

Integration usually happens in one of three places:

Backend jobs that build a payload and call the video API directly.
Automation tools that trigger renders from forms, CRM changes, ecommerce events, or spreadsheet rows.
Content pipelines where AI agents, copy tools, or image and video systems prepare assets before the final render request.

The important part is to keep the renderer's job clear. Zvid receives structured JSON, renders the video, and returns a finished output. Your surrounding workflow can decide where the content comes from, whether AI helps draft it, and where the completed video file should be stored.

Common mistakes

The most common mistake is treating the payload like a one-off export instead of a reusable contract between your application and the renderer.

When to use Zvid

Use Zvid when you want a hosted API that can turn structured video definitions into repeatable render jobs without building the rendering pipeline yourself.

Zvid is a strong fit when you need:

One payload model reused across many outputs.
Public API endpoints for auth checks, render submission, and job polling.
Control over timing, layout, text, and media through JSON.
A workflow that fits backend jobs, automation systems, and data-driven products.
A way to programmatically generate videos from JSON templates, not just a one-off visual editor export.

One JSON-driven render system can support many outputs once the payload model is stable.

If you only need occasional handcrafted edits, the API model may be unnecessary. If your inputs already exist as structured data, generating videos from JSON usually becomes much easier than maintaining the same work manually.

If that matches your use case, try one Zvid payload today, confirm the finished output, and then expand the same pattern into your real templates.

The payload visual is generated from the real renderable example in this tutorial.

FAQs

Do I need a huge payload to get started?

No. A small payload with one or two text elements is enough to prove the request flow first. Add more scene complexity only after you can submit jobs and track finished results reliably.

How do I convert JSON to video?

Create a JSON payload that describes the video, send it to a render endpoint, save the returned job ID, and poll until the API returns a completed video URL. In Zvid, the public render endpoint accepts a payload object and the jobs endpoint reports render status.

Is this the same as JSON prompting for AI video?

Not exactly. JSON prompting for AI video describes a scene for a generative model. Zvid uses structured JSON as a render payload, which is better for explicit layouts, templates, brand consistency, subtitles, media placement, and repeatable output.

Should I use preset resolutions or custom width and height?

Preset resolutions are usually the fastest starting point because they give you known output sizes. Use custom dimensions when your workflow needs a format that does not fit a preset cleanly.

Can I generate many videos from the same JSON structure?

Yes. That is one of the main advantages of this approach. Keep the scene logic stable and swap the changing inputs such as title, CTA, media URL, language, or destination format.

Can I integrate JSON video rendering with my existing workflow?

Yes. A backend service, automation tool, ecommerce job, CRM trigger, or spreadsheet workflow can prepare the structured data, create the JSON payload, call the API, and store the finished output URL.

How long does it take to generate a video from JSON?

The exact render time depends on video length, complexity, media assets, and queue state. The reliable pattern is to submit the job, poll status, and treat the video as ready only when the API returns a completed result.

What should I save from each render request?

Save the payload version, returned jobId, current state, and final output URL. That gives you enough context to debug, retry, and regenerate later.

Generating a video from JSON is mostly about getting one reliable loop working: create the payload, submit the job, poll the result, and reuse the same structure as your content changes. Zvid gives you a public API for that exact workflow, so the next practical step is to send one small render job and inspect the finished output.

JSON to Video API: Convert JSON to Video with Zvid

Mina Ramzy — Thu, 04 Jun 2026 10:16:28 +0000

A JSON to video API lets you describe a video as structured JSON data, submit that payload to a rendering endpoint, and receive a finished video file when the job completes. If you need to convert JSON to video for templates, localization, product feeds, campaign variants, or app-generated clips, that is usually a better fit than rebuilding timelines manually in a GUI.

The core workflow is simple: verify your API key, submit a payload with a POST request to /api/render/api-key, save the returned jobId, and poll GET /api/jobs/{id} until the render completes. Zvid documents that exact flow in the Getting Started guide, the Authentication guide, and the JSON Structure overview. If you are evaluating the broader automation pattern, the same principles also appear in How to Generate 1,000 Videos Automatically with an API and How to Create Product Videos from a CSV or Product Feed.

A JSON-to-video workflow turns structured inputs into repeatable renders.

Here is the public API shape most teams start with:

curl -X GET https://api.zvid.io/api/user/profile \
  -H "x-api-key: YOUR_API_KEY"

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @render-job.json

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

That request pattern matters more than any single example video. Once your application can generate valid payloads, submit jobs, and track results, the same system can power demos, onboarding videos, product videos, internal ops videos, ecommerce clips, or high-volume personalized output.

What a JSON to video API actually does

A JSON to video API separates video intent from video rendering.

Instead of storing a timeline only inside an editor, you send a structured description of the scene: canvas size, duration, background, visual layers, audio tracks, subtitle or caption timing, animation timing, and output format. The API validates that structure, queues the job, resolves any remote assets, renders the final composition, and returns a status object until the video is ready.

That is why JSON-driven video is attractive for engineering teams:

It is versionable and diffable like the rest of your application logic.
It makes video templates reusable across many content variations.
It fits cleanly into backend jobs, queues, and webhook or polling workflows.
It removes manual export steps when the creative structure is mostly stable.

If you only need one bespoke launch video, a traditional editing tool may still be faster. If you need the same video system to react to changing data, JSON starts to win.

How to convert JSON to video

At a high level, the lifecycle is: build the JSON payload, submit the render job, poll status, then store or publish the result URL. That is the practical answer to "how do I convert JSON to video?": the JSON file or JSON object becomes the source for layout, timing, media, text, and output settings.

A reliable render flow keeps payload generation, submission, and polling separate.

In practice, the flow is:

Generate or retrieve the structured content your video needs.
Map that content into one Zvid payload object.
Send the payload to POST https://api.zvid.io/api/render/api-key.
Save the returned jobId, status, and any queue metadata.
Poll GET https://api.zvid.io/api/jobs/{id} until state is completed or failed.
Use result.url when the render completes.

You can start with a static payload checked into your repo, then move to dynamically generated JSON once the first render works. For example, an ecommerce app might inject product names, prices, image URLs, and destination format into the same template. A localization workflow might keep the layout fixed while changing headline copy, subtitle language, and voiceover files.

The Submit render job and Get render job status references are the key docs to keep open while you wire this up. If you want to make the workflow safer in production, the Get credit balance and Get user profile references are also useful checks before you submit large batches.

This is the first useful CTA for most readers: do not start with a huge pipeline. Start with one payload, one render job, and one completed output. Once that loop is stable, scaling is mostly an orchestration problem.

The anatomy of a Zvid payload

Zvid's public docs define the render body as an object with a required payload. Inside that payload, the main fields are name, resolution, duration, frameRate, outputFormat, backgroundColor, visuals, audios, and subtitle. Those JSON objects give you control over every aspect that matters in a template-driven render: element types, coordinates, media URLs, timing, and platform-ready output. The JSON Structure overview, ResolutionPreset reference, and Text Elements reference are the most important references for understanding that shape.

Below is a proof-friendly Zvid API payload that renders a short landscape explainer card. It uses SVG and TEXT elements only so the structure is easy to inspect and adapt.

{
  "name": "json-to-video-api-guide-demo",
  "resolution": "hd",
  "duration": 9,
  "frameRate": 30,
  "outputFormat": "mp4",
  "backgroundColor": "#08111f",
  "visuals": [
    {
      "type": "SVG",
      "width": 1280,
      "height": 720,
      "svg": "<svg width='1280' height='720' viewBox='0 0 1280 720' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='bg' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#08111f'/><stop offset='1' stop-color='#1c2448'/></linearGradient><radialGradient id='glowA' cx='0' cy='0' r='1' gradientUnits='userSpaceOnUse' gradientTransform='translate(1040 120) rotate(90) scale(260)'><stop stop-color='#2fd4c5' stop-opacity='0.22'/><stop offset='1' stop-color='#2fd4c5' stop-opacity='0'/></radialGradient><radialGradient id='glowB' cx='0' cy='0' r='1' gradientUnits='userSpaceOnUse' gradientTransform='translate(220 640) rotate(90) scale(280)'><stop stop-color='#f4b647' stop-opacity='0.18'/><stop offset='1' stop-color='#f4b647' stop-opacity='0'/></radialGradient></defs><rect width='1280' height='720' fill='url(#bg)'/><circle cx='1040' cy='120' r='260' fill='url(#glowA)'/><circle cx='220' cy='640' r='280' fill='url(#glowB)'/><rect x='36' y='36' width='1208' height='648' rx='32' fill='rgba(255,255,255,0.035)' stroke='rgba(255,255,255,0.08)'/></svg>"
    },
    {
      "type": "SVG",
      "x": 258,
      "y": 360,
      "width": 372,
      "height": 454,
      "anchor": "center-center",
      "track": 2,
      "enterBegin": 0.2,
      "enterEnd": 0.9,
      "enterAnimation": "smoothleft",
      "exitBegin": 8.1,
      "exitEnd": 8.7,
      "exitAnimation": "fade",
      "svg": "<svg width='372' height='454' viewBox='0 0 372 454' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='card' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='rgba(255,255,255,0.14)'/><stop offset='1' stop-color='rgba(255,255,255,0.05)'/></linearGradient><linearGradient id='panel' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#2fd4c5'/><stop offset='1' stop-color='#4f78ff'/></linearGradient></defs><rect x='0.5' y='0.5' width='371' height='453' rx='30' fill='url(#card)' stroke='rgba(255,255,255,0.14)'/><rect x='28' y='30' width='124' height='30' rx='15' fill='rgba(47,212,197,0.14)' stroke='rgba(47,212,197,0.30)'/><text x='90' y='49' text-anchor='middle' fill='#9cf5eb' font-size='14' font-family='Inter' font-weight='700'>API READY</text><rect x='28' y='90' width='316' height='124' rx='20' fill='rgba(8,17,31,0.56)' stroke='rgba(255,255,255,0.08)'/><rect x='28' y='234' width='316' height='78' rx='20' fill='rgba(8,17,31,0.56)' stroke='rgba(255,255,255,0.08)'/><rect x='28' y='330' width='316' height='92' rx='20' fill='url(#panel)' opacity='0.92'/><rect x='54' y='116' width='132' height='16' rx='8' fill='rgba(255,255,255,0.22)'/><rect x='54' y='148' width='222' height='14' rx='7' fill='rgba(255,255,255,0.10)'/><rect x='54' y='176' width='176' height='14' rx='7' fill='rgba(255,255,255,0.10)'/><rect x='54' y='260' width='116' height='14' rx='7' fill='rgba(255,255,255,0.22)'/><rect x='54' y='284' width='218' height='12' rx='6' fill='rgba(255,255,255,0.10)'/><rect x='54' y='358' width='180' height='18' rx='9' fill='rgba(255,255,255,0.26)'/><rect x='54' y='388' width='122' height='12' rx='6' fill='rgba(255,255,255,0.18)'/></svg>"
    },
    {
      "type": "TEXT",
      "x": 850,
      "y": 142,
      "width": 520,
      "anchor": "center-center",
      "track": 6,
      "enterBegin": 0.5,
      "enterEnd": 1.1,
      "enterAnimation": "fade",
      "exitBegin": 8,
      "exitEnd": 8.6,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; color:#9cf5eb; font-size:18px; font-weight:700; letter-spacing:1px;'>STRUCTURED VIDEO WORKFLOW</div>"
    },
    {
      "type": "TEXT",
      "x": 850,
      "y": 258,
      "width": 520,
      "anchor": "center-center",
      "track": 8,
      "enterBegin": 0.7,
      "enterEnd": 1.4,
      "enterAnimation": "fade",
      "exitBegin": 7.9,
      "exitEnd": 8.5,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; color:#ffffff; font-family:Poppins; font-size:46px; font-weight:700; line-height:1.12;'>Send JSON. Track jobs. Render videos at scale.</div>"
    },
    {
      "type": "TEXT",
      "x": 850,
      "y": 426,
      "width": 520,
      "anchor": "center-center",
      "track": 8,
      "enterBegin": 1,
      "enterEnd": 1.6,
      "enterAnimation": "fade",
      "exitBegin": 7.8,
      "exitEnd": 8.4,
      "exitAnimation": "fade",
      "html": "<div style='text-align:left; color:#d7def6; font-size:22px; line-height:1.45;'>Define layout, timing, media, and output in JSON, then let the API queue and render the final video.</div>"
    },
    {
      "type": "TEXT",
      "x": 850,
      "y": 556,
      "width": 360,
      "anchor": "center-center",
      "track": 9,
      "enterBegin": 1.2,
      "enterEnd": 1.8,
      "enterAnimation": "fade",
      "exitBegin": 7.7,
      "exitEnd": 8.3,
      "exitAnimation": "fade",
      "html": "<div style='display:inline-block; background:rgba(244,182,71,0.20); border:1px solid rgba(244,182,71,0.42); border-radius:24px; padding:16px 24px; color:#ffffff; font-size:22px; font-weight:700;'>Start with one render job</div>"
    },
    {
      "type": "TEXT",
      "x": 640,
      "y": 654,
      "width": 1080,
      "anchor": "center-center",
      "track": 4,
      "enterBegin": 1.4,
      "enterEnd": 2,
      "enterAnimation": "fade",
      "exitBegin": 7.6,
      "exitEnd": 8.2,
      "exitAnimation": "fade",
      "html": "<div style='text-align:center; color:#c3cceb; font-size:16px;'>A small payload example is enough to prove the render loop before you scale it.</div>"
    }
  ]
}

A payload stays useful when each field has a stable responsibility in the render.

The point of this example is not the design itself. The point is the shape: one object describes the video in a way your backend can generate repeatedly.

For image-heavy workflows, the Image Elements reference explains remote image handling, while the Text Elements reference covers the safe text and HTML options most teams use for headlines, labels, and CTAs.

A practical API request flow

Once you understand the payload, the rest of the system is normal API engineering.

Start by verifying auth:

curl -X GET https://api.zvid.io/api/user/profile \
  -H "x-api-key: YOUR_API_KEY"

Then check credits:

curl -X GET https://api.zvid.io/api/credits/balance \
  -H "x-api-key: YOUR_API_KEY"

Then submit a render request:

{
  "payload": {
    "name": "json-to-video-api-guide-demo",
    "resolution": "hd",
    "duration": 9,
    "frameRate": 30,
    "outputFormat": "mp4",
    "backgroundColor": "#08111f",
    "visuals": [
      {
        "type": "TEXT",
        "text": "Hello from Zvid",
        "x": 640,
        "y": 360,
        "anchor": "center-center",
        "style": {
          "fontSize": 54,
          "color": "#ffffff",
          "textAlign": "center"
        }
      }
    ]
  }
}

Poll until the job finishes:

curl -X GET https://api.zvid.io/api/jobs/$JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

The Getting Started guide shows the same sequence with example responses. In production, the important discipline is to store the returned jobId, track status transitions, and only treat the video as complete when the jobs endpoint returns a finished result.

This is where the middle CTA makes sense: if you are still evaluating vendors or architecture, do not optimize for every edge case up front. Send one render, inspect the output, and confirm the API model fits how your product already stores data.

Video templates, animation, and dynamic output

A JSON to video workflow works best when the template is treated as a system contract. The JSON can hold fixed design rules, dynamic fields, or both. Fixed rules might include frame rate, resolution, brand colors, text styles, and animation timing. Dynamic fields might include headline text, image URLs, subtitle files, product details, prices, CTAs, and output format.

This is different from asking an AI video generator to interpret a loose text prompt. With structured JSON, the application can programmatically generate hundreds of videos while keeping the same layout and brand rules. You can still use AI-generated copy, images, or voiceovers upstream, but the render payload should stay explicit enough that the final video is predictable.

For a scalable pipeline, keep three layers separate:

Content data: the product, campaign, customer, or locale fields.
Template rules: the scene layout, text animation, element types, and fallback behavior.
Render orchestration: the API call, queue handling, retries, and final video URL storage.

Manual video tools vs JSON-driven rendering

Most teams should not think of JSON rendering as a replacement for all creative tools. It is a replacement for repeated manual export work when the video structure is stable.

Manual editors are better when every video needs hands-on creative changes.
A JSON to video API is better when the same structure repeats across many variants.
Manual editors optimize for one timeline at a time.
JSON-driven rendering optimizes for systems that can generate many timelines safely.

JSON rendering is strongest when the structure repeats and the inputs change.

If your use case is catalog automation, localization, campaign fan-out, onboarding videos, or personalized clips, the same template logic can keep paying off. That is why high-volume and feed-driven use cases often move toward structured rendering instead of more manual editing.

No-code integrations and JSON2Video alternatives

Some teams call a JSON to video API directly from a backend service. Others connect the same video automation workflow through no-code or low-code tools such as n8n, Zapier, Make, Shopify exports, CRM triggers, or scheduled spreadsheet jobs. The integration pattern is the same: collect structured data, generate the JSON payload, send the render request, and route the completed video file to the next system.

You will also see tools and category terms such as JSON2Video, video editing API, dynamic video, and programmatic video creation API in this market. The useful comparison is not only feature count. Ask whether the platform gives you enough control over templates, output formats, media handling, watermarks, API key authentication, job status, and repeatable rendering without manual editing.

For Zvid, the fit is structured video rendering through a hosted API. It is not positioned here as a prompt-only text-to-video model such as Sora, Veo, or Seedance, and it is not a hosting-only video API. It is for teams that want application data to become on-brand videos through explicit JSON payloads.

Common mistakes

The most common mistake is treating the JSON payload as a one-off export artifact instead of a reusable system contract.

Other mistakes show up repeatedly:

Mixing business data cleanup with scene layout logic in the same step
Hard-coding visual values that should come from reusable template rules
Skipping credit or auth checks before large submissions
Ignoring job-state tracking and assuming a successful submit means a finished render
Designing templates that only work for one headline length, one locale, or one media shape
Treating every provider as interchangeable without checking template control, integration needs, or output requirements

Another common failure is overfitting the first demo. A payload can look fine with one short headline and then break once real inputs are longer, translated, or missing optional media. That is why repeatability matters more than getting one perfect screenshot.

When to use Zvid

Use Zvid when you want a hosted API that turns structured video definitions into repeatable render jobs without building your own rendering pipeline.

Zvid is a strong fit when you need:

Programmatic video generation from structured app data
One template system reused across many outputs
Public API endpoints for auth checks, render submission, and job polling
Support for timed text, SVG, images, videos, audio, and subtitle-driven workflows
A scalable way to generate videos from JSON without manual editing for each variation

One structured video system can support many teams once the render loop is stable.

If you only need occasional handcrafted exports, the API model may be unnecessary. If you already have structured content and want the output video to be just another system-generated asset, it becomes much more useful.

The right next step is simple: build one small payload, render one finished video, and then decide whether your workflow needs more templates, more variations, or more orchestration around the same API core.

FAQs

Is a JSON to video API only for high-volume rendering?

No. High volume is one use case, but the same model is useful even for smaller systems when you want predictable, repeatable output from structured content.

How do I convert JSON to video?

Create a JSON payload that describes the video, send it to a render endpoint, save the returned job ID, and poll the job until the API returns a completed video URL. In Zvid, that means sending a payload to the render endpoint and tracking the job status.

Do I need to generate every field dynamically?

Not at all. Most teams keep a mostly fixed template and only inject the fields that change, such as title, subtitle, CTA, product image, locale, or destination format.

Can I render multiple videos from different JSON inputs?

Yes. Use the same template rules, generate one JSON object per variation, and submit one render job for each output. That is how teams generate videos automatically for product catalogs, localized campaigns, onboarding flows, and personalized clips.

Can I start with text and simple graphics before I add remote media?

Yes. That is often the safest way to prove the payload model first. Then you can expand into remote images, video clips, audio, or subtitles as the use case gets more complex.

Can I connect a JSON to video workflow to n8n, Zapier, or Shopify?

Yes, as long as the integration can prepare structured data and make authenticated API requests. Many teams use no-code tools for triggers and routing, while keeping template logic and render validation in application code.

What should I save from each render request?

Save the payload version, the returned jobId, the current job state, and the final output URL once the job completes. That gives you enough information to debug, retry, or regenerate later.

If your product already thinks in structured inputs, a JSON to video API is usually the cleanest path to repeatable rendering. Start with one Zvid payload, one render job, and one completed output, then expand only after that loop feels reliable.

The payload visual is generated from the article's real render example.

JSON to Video

Mina Ramzy — Wed, 25 Feb 2026 16:03:59 +0000

I spent the last 1.5 years creating an open-source npm package that leverages FFMPEG to render videos at a large scale via JSON

It supports:

Images, videos, GIFs, SVGs
Text & HTML
Audio
Timing, Tracking, animations, transitions, filters, chroma key, zoom, styling, etc.

Why did I build it?

Mainly for Video automation.

Nowadays, in the age of AI, automated videos are everywhere:

marketing videos
social content at scale
personalized videos
programmatic content pipelines

Most existing tools are either:

GUI-only (hard to automate)
too low-level (FFmpeg scripts everywhere)

Zvid sits in the middle.

How to use it?

You can use it with just one terminal prompt.

First, make sure you have Node.js installed on your system.

Create a JSON file to define your Video JSON structure (ex: example.json )

{
  "name": "example",
  "backgroundColor": "#753C73",
  "visuals": [
    {
      "type": "text",
      "text": "Welcome, Zvid!",
      "position": "center-center",
      "style": {
        "color": "#ffffff"
      }
    }
  ]
}

And in the terminal run

npx zvid render example.json

What I would love feedback on

Feel free to check the source code from GitHub. If you liked the idea and felt you would use it one day, don't forget to put a ⭐ on GitHub

I’d also love your thoughts on:

Did you like the idea?
What do you think are the best use cases?
Would you share it with someone who needs it?

DEV Community: Mina Ramzy

Bulk AI Video Generation API: How to Generate 1,000 Videos

The bulk video generation architecture

Copy-paste Zvid bulk render payload

How the API workflow works

Design the job queue before the template

Build render payloads from structured data

Where AI video generation APIs fit

Polling, retries, and failure handling

Common mistakes

How to choose a bulk video generation API

When to use Zvid

FAQs

What is a bulk video generation API?

Is bulk video generation the same as text-to-video generation?

How do I generate 1,000 videos automatically?

Should I submit all 1,000 render jobs at once?

What should I store for each generated video?

How do retries work in bulk video rendering?

Can I use product feeds or CSV files for bulk video generation?

Does every video need a different JSON payload?

When is bulk rendering better than manual editing?

Can AI models be part of a bulk video workflow?

What features matter in a bulk video generation API?

AI B-roll Generator API: Automate with JSON

The JSON model for automated B-roll

Copy-paste Zvid B-roll timing payload

How the B-roll workflow works

Mapping B-roll plans from scripts or data

Where AI video and B-roll footage fit

Timing, tracks, resize, and transitions

API workflow for rendering B-roll

Common mistakes

When to use Zvid

FAQs

What is automated B-roll?

Can I add B-roll with JSON?

Which fields control B-roll timing?

How do I keep B-roll from covering titles or captions?

Should B-roll video clips include audio?

Can I use images instead of video clips for B-roll?

How do I choose between cover and contain?

Can AI help choose B-roll cues?

Is B-roll automation useful for product videos?

Add Subtitles to Video with JSON: API Tutorial

The JSON subtitle model

Copy-paste Zvid caption payload

How the subtitle workflow works

Subtitle display modes and styles

API workflow for rendering captions

Adding subtitles to an existing video file

Common mistakes

When to use Zvid

FAQs

What fields are required for Zvid subtitles?

Do I need word-level timings?

Can I style subtitles with JSON?

Where does the subtitle object go?

Can I use subtitles with generated or feed-based videos?

How should I validate subtitle JSON?

How do I add subtitles to an already recorded video?

Can AI tools generate subtitles for this workflow?

Are subtitles the same as closed captions?

Product Video API: How APIs Power CSV Video Generation

Why feed-driven product video works

Product video API workflow

What is a product video API for video creation?

REST API pipeline and API key setup

Map feed columns into a reusable Zvid template

Example Zvid API payload for one product video

Video editing vs feed-driven rendering

Video generation API use case checklist

AI video generator, no-code, and ecommerce integrations

Common mistakes

When to use Zvid for video automation

FAQs

Which type of video API do I need?

Can I automate video creation with a video API?

Can I create many videos from one CSV file?

Do I need a different template for every product category?

How do I choose between `cover` and `contain`?