Ecommerce Video API for Product Ads: A Practical Integration Guide

An ecommerce video API for product ads is useful when your product needs repeatable ad-video creation from product images, not a one-off creative demo. The API should accept assets, return a task id quickly, expose task state, charge credits predictably, and deliver a hosted MP4 your system can store or publish.

• Use POST /v1/ecommerce-video/tasks when a product image set and short creative brief should become a paid-social or landing-page video.
• Keep product images as public HTTPS URLs, or upload local assets with POST /v1/files before task creation.
• Treat video creation as async: create the task, poll GET /v1/tasks/{task_id}, and add webhooks when polling is not enough.
• Budget with the launch rate: Ecommerce Video is 15 credits per second at 1080p, so a 15-second ad reserves 225 credits.
• Do not expose upstream provider ids, temporary URLs, or provider-specific states to your customers.

Quick answer

Choose an ecommerce video API for product ads when the integration has to survive real catalog operations: multiple product images, short durations, aspect-ratio variants, account credits, concurrency, task logs, webhooks, and stable output URLs.

Do not choose it just because "AI video" is interesting. Use it when a product manager or growth team asks for a repeatable system:

• Generate one product ad video from one to seven product images.
• Keep each ad request attached to an account, API key, request id, and credit ledger.
• Produce 9:16, 1:1, or 16:9 variants without changing the customer-facing contract.
• Let support teams inspect one task record when a campaign asset fails.
• Return hosted MP4 output instead of making customers chase provider files.

That is the product difference between a raw model call and a workflow API.

The workflow shape

The core loop is intentionally small:

1. Upload or host product images.
2. Create an Ecommerce Video task.
3. Store the returned task_id and request_id.
4. Poll the task every 5-10 seconds with jitter, or receive task.succeeded and task.failed webhooks.
5. Read output.media[].url when the task succeeds.
6. Show final usage and errors from the task record, not from provider logs.

The contract is public and workflow-shaped:

export BEATAPI_API_KEY="sk_your_key"

curl https://api.beatapi.io/v1/ecommerce-video/tasks \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["https://media.beatapi.io/samples/smart-bottle.png"],
    "duration": 15,
    "prompt": "Fast product launch ad for paid social.",
    "aspect_ratio": "9:16",
    "language": "en"
  }'

A successful create request returns 201 with a queued task. For a 15-second ecommerce ad, launch pricing reserves and charges 225 credits:

{
  "data": {
    "id": "task_p9Lm2",
    "object": "task",
    "workflow": "ecommerce-video",
    "status": "queued",
    "stage": "queued",
    "output": null,
    "usage": {
      "credits_reserved": 225,
      "credits_charged": 225,
      "billable_duration_seconds": 15,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_def456",
    "error_code": null,
    "error_message": null
  }
}

When to use it

Use the Ecommerce Video API when your team is building one of these product surfaces:

Use a lower-level video model API instead when you want to experiment with model behavior directly, when billing and support do not need to attach to the generation task, or when the user expects manual creative control more than repeatable automation.

Request contract

BeatAPI keeps the launch request compact:

• images is required. Provide one to seven public HTTPS image URLs.
• duration is required. Use an integer from 10 to 60 seconds.
• prompt is optional and can be up to 2000 characters.
• aspect_ratio is optional and supports 16:9, 9:16, and 1:1.
• language is optional and supports en or zh.

The narrow contract is intentional. Product-ad systems usually fail because they let too many provider-specific controls leak into customer integrations. A stable ecommerce video API should let the product team improve routing, validation, retry behavior, and providers behind the same public shape.

Prompt anatomy for product ads

Keep prompt text operational, not poetic. A useful prompt tells the workflow what the product is, what the ad should emphasize, and what channel the output is for:

Create a 15-second vertical product ad for a smart insulated bottle.
Show the bottle in clean close-ups, then in an active commuter scene.
Emphasize cold retention, leak-proof carry, and a modern matte finish.
Use fast paid-social pacing, bright natural light, and concise on-screen benefit beats.
Avoid medical claims, fake discounts, and unreadable small text.

That prompt is still secondary to the asset contract. The images carry product identity; the prompt directs pacing, claims, and use case.

Worked example

Imagine a commerce platform that wants every seller to create one video ad from a product detail page.

The product team should not build the UI around model settings. It should build around the product job:

Polling remains the source of truth even if the platform also uses webhooks:

curl https://api.beatapi.io/v1/tasks/task_p9Lm2 \
  -H "Authorization: Bearer $BEATAPI_API_KEY"

When the task succeeds, store the hosted MP4 URL from output.media. Do not make the customer depend on temporary provider URLs or internal job ids.

Production checklist

Before you ship an ecommerce video API integration, check these operational details:

• Image URLs are public HTTPS URLs and are reachable from BeatAPI.
• Local seller uploads go through /v1/files before task creation.
• Duration is clamped to 10-60 seconds in your UI before submission.
• Aspect ratio is selected before the user approves the creative brief.
• Your backend stores task_id, request_id, workflow, status, usage, and output URL.
• Polling uses a 5-10 second interval with jitter, not a tight loop.
• Webhook handlers verify BeatAPI signatures and still allow polling fallback.
• User messaging distinguishes queued, processing, succeeded, and failed.
• Credit estimates are shown before batch creation.
• Failed tasks expose error_code and error_message to support staff, not only to logs.

Mistakes and fixes

FAQ

What is an ecommerce video API for product ads?

It is an API workflow that turns product images, a short creative brief, duration, and output format into an asynchronous product ad video task. In BeatAPI, the launch endpoint is POST /v1/ecommerce-video/tasks.

How many product images should I send?

Send one to seven public HTTPS image URLs. Use the clearest product images you have: front view, detail view, packaging, and lifestyle context if available.

Can I upload local product files?

Yes. Use POST /v1/files for local assets first, then pass the returned HTTPS URL into the ecommerce video task.

How long can a product ad video be?

The Ecommerce Video API launch contract accepts duration from 10 to 60 seconds. Shorter durations usually fit paid-social and marketplace use cases better.

How should I estimate credits?

Ecommerce Video uses 15 credits per second at 1080p in the current launch catalog. A 10-second task is 150 credits; a 15-second task is 225 credits; a 30-second task is 450 credits.

Should I use polling or webhooks?

Start with polling because it is easier to debug. Poll GET /v1/tasks/{task_id} every 5-10 seconds with jitter. Add webhooks when you need backend completion events, but keep the task endpoint as the source of truth.

What output should my app store?

Store the BeatAPI task id, request id, final status, usage object, and output.media[].url. The media URL is the customer-facing MP4 output.

Is this only for paid social ads?

No. Product teams can also use it for marketplace listing videos, landing-page hero videos, offer tests, and creative variants. The same task contract works across those surfaces.

When should I avoid this workflow?

Avoid it when you need direct low-level model experimentation, frame-by-frame editing, or a manual creative suite. The Ecommerce Video API is designed for repeatable product ad automation.