A marketplace video API connects listing videos to the platform's own pages and data. Videngine's API, on Growth and above, is read-only: your systems look up the approved video for a listing by stock number, list and fetch versions with their cuts, captions, chapters and transcript, and read the publishing history. Videos are made in the studio and in batch runs, or on the Custom plan by inventory sync, with delivery into listings through one stable link per listing that only plays a reviewed cut.
Marketplace video API: what exists today
Videngine's marketplace video API is a read API: your systems read the videos and their review status, and the videos themselves are made inside Videngine.
The lead guide, marketplace listing video for every listing on the platform, covers why the platform should make the video, seller rights, quality gates and the rollout. This page covers the API side of a video for every listing: how it joins your platform's data and listing pages.
Videos are made in the studio, from a listing's link or from pages picked from your sitemap, and from Growth in batch runs from CSV or JSON. API access starts on Growth, and reviewer sign-off with defect codes on Scale. Inventory sync and delivery straight into listings, including one stable link per listing, come with Custom, from 1,500 videos a month.
As a listing video API, it answers five kinds of request:
- Lookup. The approved video for a listing, by stock number or SKU, or by the address of a file Videngine published.
- Versions. Every version, newest first, filtered by status or by updated since a given time.
- One version in full. Each cut's dimensions, file, poster and captions URLs, plus chapters and the timed transcript.
- Captions. Each cut's captions as WebVTT.
- Publishing history. Every upload to a listing, in order.
There is no public endpoint for creating or editing videos, no webhooks and no SDK. Every video is reviewed in the studio before it goes out.
Integration patterns for listing video
An automated listing video integration usually needs one or two of five patterns: a link in the listing template for playback, and the read API for data, captions and reporting.
| Pattern | How it works | Plan | Watch for |
|---|---|---|---|
| Stable link in the listing template | The template embeds the listing's one stable link. It only plays a cut that passed review, and switches to the new cut when a rebuild is approved. | Custom | Until the first cut passes review there is nothing to play, so the page must render without a player. |
| Lookup at page render | The page server looks up the listing's approved video by stock number, or lists its versions and takes the newest that passed review, then renders a player with its poster and captions. | Growth and above | Rate-limited per key. Cache each answer; never call the API from the browser. |
| Nightly job | A job lists versions updated since its last run, keeps those that passed review and writes their URLs into your listing table, which pages read. | Growth and above | Store the last run time, page through results, and wait when asked to. |
| Captions and transcript on the page | Fetch the version in full, store its WebVTT and serve it yourself as a captions track, and print the transcript and chapters under the player. | Growth and above | Use the version actually playing, not the newest. |
| Publishing history for reporting | Read every upload in order and join it to your listing table. | Growth and above | Join on your platform's own listing ID, not a seller's stock number. |
The nightly job is the safer default: pages render from your own database, so a slow answer from Videngine never holds one up. We publish no uptime figure, so build pages to render without the video. Player placement and poster-first loading are covered in putting a video on every detail page.
Captions belong on the page as well as in the file. The W3C's WebVTT specification says WebVTT files provide captions or subtitles for video, for use with the HTML track element; give that element kind="captions". WCAG 2.2 success criterion 1.2.2, at Level A, asks for captions for all prerecorded audio in synchronised media. The printed transcript also puts the narration into the page's own HTML; see video transcripts and captions and VideoObject schema.
Build on a rendering API, or buy finished listing videos
A rendering API gives you a renderer to build a listing-video product on; Videngine gives you a finished, reviewed video for each listing. Both get called a video API for marketplaces, but your team builds very different things around each.
Shotstack's documentation describes edits as JSON timelines rendered in the cloud, with a webhook when each is ready. Creatomate has you design a template in its editor, then call its REST endpoint to render it with your data. Videngine vs Shotstack and Videngine vs Creatomate compare price and features, and what to evaluate in a video automation API covers jobs, retries and callbacks.
Building on a rendering API, your team owns the mapping from each category's fields to a script, the voice and pronunciation list, caption timing from the finished audio, a review queue where the approver is not the builder, versioning when a price or photo changes, and delivery to the listing. With Videngine those are included, and your team owns the integration: the join key, the template change and the nightly job.
Building on a rendering API is the better choice when:
- Sellers should edit their own video in your app. Shotstack offers a white-label video editor to embed, and Creatomate a JavaScript Preview SDK for web-based editing.
- Your own events must start a render. If a listing going live should trigger a render and a callback, you need a create endpoint; Videngine's API only reads.
- Video is a product you sell to sellers, with your own templates and pricing.
- Narration must be in other languages. Videngine narrates in English only.
The data contract: join keys, changes and versions
Agree one join key before the backfill: your platform's listing ID, with the seller's stock number carried beside it.
Videngine names files by stock number or reference, and the API looks videos up by stock number or SKU. On a marketplace, stock numbers belong to sellers, so two dealers can both list stock number 1042 (illustrative). Use a key that is unique on the platform and never reused, usually the listing ID, in every batch row or sync. Store the version you play beside the listing, and fetch captions and transcript for that version, so the words on the page match the cut.
| Listing event | In Videngine | On your platform |
|---|---|---|
| Price change | Re-render. The rebuild is saved as _v2 beside the original, free in the same month. The stable link keeps playing the approved original until the rebuild passes review. | If the narration states the price, hide the player until the rebuild is approved, or use a price policy that leaves the price out. |
| Photos or facts edited | A rebuild, reviewed before it replaces the original | Send the change in the next batch or sync. |
| Sold or closed | The ledger keeps every version as a record. On Custom, the rollout agrees how inventory sync treats a closed listing. | Your listing state wins: hide the player when the listing closes, whatever the video's status. |
| Relisted, same listing ID | Existing versions still belong to the listing. | Check the photos and facts; if anything changed, rebuild before the video shows again. |
| Relisted, new listing ID | A new listing; earlier versions stay in the ledger. | Render fresh unless the photos and facts are identical. |
Platforms with a fixed close, such as timed auctions, have their own timing for retiring a video; see auction lot video.
Versions keep old links working. A rebuild is saved beside the original, never over it, so a page or cache holding the old address plays an older reviewed video, not a broken one. That video may state an old price, so find stale links: looking up an older file's address returns its version marked as no longer current, and the publishing history shows when the listing moved on.
Review and API keys at platform scale
At platform scale, only reviewed videos should reach a listing, and only the systems you name should be able to read them.
Review as part of the contract
The marketplace listing video guide sets out the quality gates, the review model and every defect code. For the integration they give four guarantees:
- Nothing unreviewed plays. The stable link only plays a cut that passed review. With the read API, filter versions by status and play only those that passed.
- The approver is not the builder. A workspace can require it, so nobody builds and ships a video alone. Reviewer sign-off and defect codes come with Scale and above.
- Defects point to an owner. Specification and photo defects usually mean a feed mapping or photo gate for the platform team to fix; pronunciation, audio, brand, render and mobile defects are fixed in the lexicon or scene set.
- The ledger is the audit trail. It records each version's builder, reviewer, status and defect code, and exports to CSV for a join against live listings.
API keys
Keys are made and revoked in Studio settings by the workspace's owners and admins; members cannot see them.
- Read-only, one workspace. A key reads one workspace's videos, versions, captions and publishing history. It cannot create, edit, approve or delete anything.
- Shown once. The key is displayed when it is made and never again, so put it in your secrets manager straight away.
- Server-side only. A key reads every video in its workspace, so keep it out of browser code and apps. Pages play from the stable link or from URLs your server stored.
- Rate-limited per key. Cache answers in your own store, and wait when the API asks you to.
- Revoked at once. A revoked key stops working. Replace keys when someone with access leaves.
When Videngine is the wrong tool for a marketplace
Videngine makes and reviews videos from listings you already hold; it does not take uploads, stream live or give sellers an editor.
| Job | Why Videngine does not fit | Better option |
|---|---|---|
| Sellers upload their own video | It does not accept, host or moderate uploads | A video hosting service with uploads and transcoding, plus your trust and safety tools |
| Live video: viewings, live auctions or calls | It has no live video | A live streaming or video-call service |
| An in-browser editor for sellers | There is no seller-facing editor | A rendering API with an embeddable editor, such as Shotstack's white-label editor or Creatomate's Preview SDK |
| Creating videos from your code on demand | The API is read-only, with no create endpoint and no webhooks | A rendering API built around jobs and callbacks |
| Narration in other languages | Narration is English only | A tool that narrates in your listings' language |
Questions platform teams ask about a marketplace video API
Does Videngine have a marketplace video API?
Yes, on Growth and above. It is read-only: look up a listing's approved video by stock number, fetch its versions, cuts, captions, chapters and transcript, and read the publishing history. Each key reads one workspace.
Can we create videos through the API?
No. There is no public endpoint for creating or editing videos, and no webhooks. Videos are made in the studio, from CSV or JSON batch runs on Growth and above, or by inventory sync from your site on the Custom plan.
What happens to a listing's video when its price changes?
Re-render it. The rebuild is saved as _v2 beside the original and is free within the same month. On Custom, the listing's stable link keeps playing the approved original until the rebuild passes review, then switches to it.
How do we know which listings have an approved video?
Run a nightly job that lists versions updated since its last run and keeps those that passed review, or export the video ledger to CSV. Join either to your live listings on your join key.
Should we build on Shotstack or Creatomate instead?
Build on a rendering API if sellers need an editor in your app, your own events must trigger renders, or you sell video as a product. Buy finished, reviewed listing videos if you would rather not build the script, voice, captions and review yourself.
Choose your next step
Plan the rollout, see the sibling guide for auctions, or check what any video API should offer.
Start with one category's feed.
Bring a sample of listing IDs and stock numbers and a slice of your sitemap. Agree the join key, the integration pattern and the review model, then plan the backfill.
Join the waitlist ↗Published by Videngine, a video rendering product built and run by Wall & Fifth. External links refer to the original documentation or product descriptions; examples are illustrative unless stated otherwise.