API quickstart

The VidSoon API is JSON over HTTPS on this origin. It creates short AI video clips from published templates — each job costs 100 credits and runs asynchronously.

Generation access is restricted on this deployment: a normal signup or API key does not unlock real inference, and live billing checkout is currently off. Approved accounts only — contact support@vidsoon.com.

Authentication

Create an API key in the console under API keys, then send it as a bearer token. Browser sessions use cookies; keys are for servers and scripts.

Authorization: Bearer <your-api-key>

List templates

GET /v1/video/templates is public — it returns each template's slug and its fields contract (name, label, max length, required), plus generation_enabled and generation_access for the deployment. GET /v1/video/status reports provider state without credentials.

Create a job

POST /v1/video/jobs takes a template_slug and a params object matching that template's fields. For product-orbit the fields are product (required, ≤80 chars) and backdrop (optional, ≤60 chars):

curl -X POST https://vidsoon.com/v1/video/jobs \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-job-001" \
  -d '{
    "template_slug": "product-orbit",
    "params": {
      "product": "a matte black insulated water bottle",
      "backdrop": "warm terracotta studio"
    }
  }'

The two-photo persona templates (hotel-lobby, ai-zombie) are served by the separate /v1/photo/* endpoints — uploaded images bound to your account, not text fields — and are in internal testing.

Creating a job reserves 100 credits. The response is a job object with id, status, and settlement; text inputs are content-screened before admission.

Photo uploads

Persona templates take exactly two ordered photos. Upload each file with POST /v1/photo/assets — a raw image body carrying x-photo-role and x-photo-consent headers — then create the job with POST /v1/photo/jobs and the two returned asset ids.

• Accepted inputs are JPEG, PNG and WebP. The browser normalizes each file to a longest side of 1024px (shortest side at least 240px) and uploads a JPEG of at most 5 MiB. The 5 MiB limit applies to the normalized upload, not the original file — the server re-decodes and re-checks the same contract.
• Uploads are bound to your account and to the role you picked. Swapping the two roles re-uploads both files — an asset is never re-used under the wrong role.
• Unbound uploads become eligible for cleanup 24 hours after upload; photos attached to a job stay while it runs or is reviewed. See Privacy for retention.
• A confirmed-failed generation releases its 100-credit reservation automatically — see Refunds.

Poll and sync

Generation is asynchronous. Poll GET /v1/video/jobs/:id, or call POST /v1/video/jobs/:id/sync to reconcile a job that looks stuck. GET /v1/video/jobs lists your 50 most recent jobs.

• succeeded — result_url is set; download below.
• failed — a confirmed failure: the credit reservation is released automatically.
• needs_review — the outcome is uncertain (e.g. the provider timed out on submit). Do not resubmit — call /sync or wait for review; a duplicate POST would start a second job.

Download the clip

GET /v1/video/jobs/:id/artifact streams the finished MP4 — owner-only, range requests supported. Artifacts are downloadable for 30 days; expired downloads return 410 artifact_expired. Provider URLs are never exposed — always use result_url.

Idempotency

POST /v1/video/jobs requires an Idempotency-Key header (up to 128 chars). Retrying with the same key and same body replays the original job — never a second charge; the same key with a different body returns 409 idempotency_mismatch. Mint a new key when the input changes.

Error codes

Errors carry error.code, error.message, and error.request_id — quote the request id when contacting support@vidsoon.com. All generation is subject to the Acceptable Use Policy.