Build with the VideoForce API
Upload source videos, then generate winning ads and highlight clips from them — programmatically. Generation is asynchronous: you submit a job, poll it, and fetch the result. Every endpoint below is testable right here in your browser.
Overview
The VideoForce API is organized around REST. It has resource-oriented URLs, accepts and returns JSON, and uses standard HTTP verbs and status codes. Errors are returned as RFC 9457 application/problem+json.
/public/v1 — e.g. https://api.videoforce.ai/public/v1/projects
AuthAuthorization: Bearer <api-key> on every request
AsyncAd & highlight generation return a job you poll, then fetch its result
BillingPer organization — included ads on your plan, then $24 per ad. See Billing & plans
Authentication
Authenticate by sending your secret API key as a Bearer token on every /public/v1 request except GET /public/v1/ping, which is deliberately unauthenticated so you can check connectivity. Keep keys server-side; never ship them in browser or mobile client code.
| Header | Value |
|---|---|
| Authorization | Bearer vf_live_… |
| Content-Type | application/json (on requests with a body) |
| X-Active-Workspace | Workspace id — required when the key is attached to more than one (see below) |
Getting a key
API keys are created and managed in the VideoForce dashboard under Organization → API Management (organization owner or admin only). A key belongs to your organization and is attached to one or more workspaces.
Choosing the workspace
Every data request resolves to exactly one workspace. How it is chosen depends on how many live attachments the key has:
| Key has… | Result |
|---|---|
| Exactly one live attachment | That workspace is used. The header is optional. |
More than one, and no X-Active-Workspace header | 400 workspace-selection-required. The body lists the attached workspace ids in context.attached_workspace_ids. |
A valid X-Active-Workspace header | That workspace is used, provided the key is attached to it. |
| A header that is not an integer, or names a workspace the key is not attached to | 404 — the two cases are deliberately indistinguishable. |
| No live attachments at all | 403 no-active-workspace-attachments. |
X-Active-Workspace explicitly if your key may gain attachments.vf_live_…) exactly once. Copy it immediately and store it in a secret manager — it cannot be retrieved again. Rotating a key revokes the previous one immediately.Failed authentication
A missing, malformed, revoked, or expired key returns 401 with a uniform "Invalid API key" body — the API does not reveal which of those it was.
Quickstart
End to end in five steps: set your key, create a project, upload a source video, generate highlights, and generate an ad. All examples use production.
1 · Set your API key
Store the key in an environment variable so it never lands in source control.
# macOS / Linux export VIDEOFORCE_API_KEY="vf_live_your_key_here" export BASE="https://api.videoforce.ai/public/v1" # Windows PowerShell (current session) $env:VIDEOFORCE_API_KEY = "vf_live_your_key_here" $env:BASE = "https://api.videoforce.ai/public/v1"
2 · Create a project
Every video and every generated asset belongs to a project, so you need one before uploading. Keep the returned id.
curl "$BASE/projects" \ -H "Authorization: Bearer $VIDEOFORCE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Summer Launch"}'
3 · Upload a source video
Uploading is three moves: create the record and get a short-lived signed URL, PUT the raw bytes to that URL (echoing every header in upload_headers verbatim), then poll the video until its status is ready.
import os, time, requests BASE = "https://api.videoforce.ai/public/v1" KEY = os.environ["VIDEOFORCE_API_KEY"] auth = {"Authorization": f"Bearer {KEY}"} PROJECT_ID = "<your-project-id>" PATH = "/path/to/video.mp4" # 1. create the record + get a signed upload URL r = requests.post(f"{BASE}/videos/upload", headers=auth, json={ "filename": os.path.basename(PATH), "content_type": "video/mp4", "size_bytes": os.path.getsize(PATH), "project_id": PROJECT_ID, }) r.raise_for_status() v = r.json(); video_id = v["video_id"] # 2. PUT the bytes straight to storage — send upload_headers verbatim with open(PATH, "rb") as f: requests.put(v["upload_url"], headers=v["upload_headers"], data=f).raise_for_status() # 3. poll until ready: uploading -> processing -> ready while True: d = requests.get(f"{BASE}/videos/{video_id}", headers=auth).json() print("status:", d["status"]) if d["status"] in ("ready", "failed"): break time.sleep(10) print(video_id, d["status"])
video_id — you'll pass it to highlights and ads. A video must be ready before you can generate from it.4 · Generate highlights, then poll & fetch
Trigger extraction, then follow the async pattern: poll the job to a terminal status, then fetch its result. See Job lifecycle for the full model.
# submit — returns 202 with a job_id + poll_url curl "$BASE/highlights" \ -H "Authorization: Bearer $VIDEOFORCE_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"project_id":"<project>","video_id":"<video>"}' # poll until status is terminal (succeeded | succeeded_empty | failed | aborted), # then fetch the result. Check the status — do NOT loop on it blindly. curl "$BASE/jobs/<job_id>" -H "Authorization: Bearer $VIDEOFORCE_API_KEY" curl "$BASE/jobs/<job_id>/result" -H "Authorization: Bearer $VIDEOFORCE_API_KEY"
5 · Generate a winning ad
Send an inline brief plus one or more source video_ids. All eleven brief fields are required and non-empty — the seven narrative fields plus target_audience, audience_age, audience_gender and tone. Same async flow — poll the returned job, then fetch its result. See POST /ads for the full field reference.
{
"project_id": "<project>",
"ad_type": "winning_ad",
"brief": {
"name": "Summer launch — hero ad",
"description": "30-second UGC-style ad introducing the summer bundle.",
"product_name": "GlowMax Serum",
"selling_point": "Visible results in 7 days",
"goals_and_outcomes": "Drive first-time purchases from paid social.",
"pain_points": "Dull skin and complicated multi-step routines.",
"campaign_brief": "Position the serum as the one-step upgrade to any routine.",
"target_audience": "Skincare-curious women who follow beauty creators on Instagram.",
"audience_age": ["25-34"],
"audience_gender": ["female"],
"tone": "friendly"
},
"video_ids": ["<video>"]
}broll_video_ids. Leave the field out (or send []) to generate without B-roll.Environments
Point requests at the host for your environment. The base path /public/v1 is identical across all of them.
| Environment | Base URL | Status |
|---|---|---|
| Production | https://api.videoforce.ai/public/v1 | available |
| Staging | https://api.stg.videoforce.ai/public/v1 | available |
| Development | https://api.dev.videoforce.ai/public/v1 | available |
https://api.videoforce.ai) — it appends /public/v1 itself. Pasting a full URL from the table above gives you …/public/v1/public/v1/… and a 404. Requesting the bare base path also returns a 404 by design — it isn’t an endpoint. To check connectivity, call GET /public/v1/ping, which returns {"status":"ok"} without authentication.Job lifecycle
Ad and highlight generation are long-running, so they're asynchronous. The trigger call doesn't return media — it returns a job handle you poll until it reaches a terminal state, then you fetch the result.
POST /ads or POST /highlights — 202 with job_id, status: "queued", and poll_url.GET /jobs/{job_id} until status is terminal. Non-terminal responses carry a Retry-After header (seconds) — use it as your backoff.GET /jobs/{job_id}/result returns the produced resources with fresh signed download URLs. Call it again anytime to mint new URLs.Job statuses
| Status | Terminal? | Meaning |
|---|---|---|
| queued | no | Accepted, waiting for a worker. |
| processing | no | Declared in the status vocabulary, but not emitted today — jobs move straight from queued to a terminal state. Handle it, don’t wait for it. |
| succeeded | yes | Done — /result returns the produced resources. |
| succeeded_empty | yes | Completed but produced no output. In practice this is a highlights outcome (no highlights found); an ad job that produces nothing ends failed with error.code: "no_output" instead. /result returns an empty resources array. |
| failed | yes | Generation errored — see the job's error object. |
| aborted | yes | Stopped before starting (e.g. insufficient credits) — never billed. |
Poll until status is one of succeeded, succeeded_empty, failed, or aborted — these are final and will not change. Retry-After on a non-terminal poll is 5 seconds.
Partial success is succeeded. A job where some inputs failed still reports succeeded with progress.failed > 0 — check the counters, not just the status. Note that progress is only filled in once the job finishes.
Why a job failed
A failed job carries error.code:
| error.code | Meaning |
|---|---|
| timeout | The job passed the 90-minute hard deadline and was reaped. |
| no_output | The pipeline finished but produced no usable ad. |
| pipeline_missing | The upstream pipeline record could not be found. |
| free_quota_exhausted | A background billing refusal — see Billing & plans. |
| outstanding_balance | A background billing refusal — see Billing & plans. |
| unknown | Anything else; read error.message. |
Treat an unrecognised error.code as unknown — new values can appear within v1.
A complete poll loop
import time, requests def run_and_wait(base, key, path, body): auth = {"Authorization": f"Bearer {key}"} # submit job = requests.post(f"{base}{path}", headers={**auth, "Idempotency-Key": __import__("uuid").uuid4().hex}, json=body).json() job_id = job["job_id"] # poll with backoff, honoring Retry-After delay = 3 while True: r = requests.get(f"{base}/jobs/{job_id}", headers=auth) d = r.json() if d["status"] in {"succeeded","succeeded_empty","failed","aborted"}: break time.sleep(int(r.headers.get("Retry-After", delay))) delay = min(delay * 2, 30) if d["status"] == "failed": raise RuntimeError(d["error"]) if d["status"] == "succeeded": return requests.get(f"{base}/jobs/{job_id}/result", headers=auth).json() return {"resources": []} # succeeded_empty / aborted
expires_at). Don't store the URL — store the resource_id/media_file_id and re-call /result to mint fresh links. Webhook callbacks (to avoid polling) are planned but not available in v1.Rate limits
Generation jobs are limited per organization across three windows. Exceeding one returns 429 with IETF RateLimit policy headers.
| Window | Limit | Retry-After |
|---|---|---|
| Concurrent jobs (queued + processing) | 5 | — (slots free as jobs finish) |
| Jobs per hour | 30 | 3600 |
| Jobs per UTC day | 150 | seconds to midnight |
aborted — including one refused for payment — consumed an hourly and daily slot. A retry loop against a 402 will exhaust the window.| Header | Description |
|---|---|
| RateLimit-Policy | All policies, e.g. "concurrency";q=5, "hourly";q=30;w=3600, "daily";q=150;w=86400. |
| RateLimit | The blocked policy with remaining r=0. |
| Retry-After | Seconds until the window resets (hourly/daily blocks only; absent for concurrency). |
The 429 body carries context.code so you can tell the three windows apart: org_concurrency_exceeded, org_hourly_jobs_exceeded or org_daily_jobs_exceeded.
Billing & plans
Billing is per organization and is managed in the VideoForce dashboard — plans cannot be bought or changed over the API, and a payment card can never be captured on an API request. What the API does expose is what each job costs and whether each produced ad has been paid for.
Plans
Every plan includes a number of generated ads per monthly billing period. Beyond that allowance each additional ad is charged at the pay-as-you-go price of $24, as long as a payment card is on file. Unused included ads do not roll over — each period starts with a fresh allowance.
| Plan | Price | Included ads per period | Effective cost per included ad |
|---|---|---|---|
| Boost | Free | 3 | — |
| Pro | $99 / month | 5 | $19.80 — 17% below pay-as-you-go |
| Studio | $249 / month | 15 | $16.60 — 30% below pay-as-you-go |
| Enterprise | Contact sales | Agreed with sales | — |
Allowance rules worth knowing
- Boost’s free ads are per person, not per organization. They attach to one organization per owner for that person’s lifetime. If you own several organizations, only one of them has the free allowance; the others start at zero.
- Pro and Studio allowances apply only while the subscription is active. A lapsed or past-due subscription loses them.
- Billing periods are anniversary-based, not calendar months — they roll on the day of the month the organization started (or last changed plan), clamped for short months.
- Failed ads are never charged. Only ads that actually render are billable.
- No endpoint exposes the remaining allowance. You cannot pre-flight how many included ads are left — track your own usage, or read it in the dashboard.
POST /highlights costs nothing on these plans and its credits_reserved comes back null.What one call can cost
One POST /ads is not one ad. The number of ads produced is derived from how many source videos you send, and every ad is billed separately:
| Source videos sent | Ads the job may produce | Maximum charge for that one call |
|---|---|---|
| 1–3 | up to 5 | 5 × $24 = $120 |
| 4 or more | up to 7 | 7 × $24 = $168 |
These are upper bounds, not exact counts — a job often produces fewer. Included ads are consumed first, so the charge applies only to the ads beyond your allowance. Highlights are free and never count toward this.
How a job is billed
/result again once it has.POST /ads returns billable_count and amount_cents as null: the cost is not known yet at submit time. Read the resolved figures from GET /jobs/{job_id}/result.No card on file: three different outcomes
A missing payment card does not reliably produce an error. One POST /ads can produce several ads (see below), and the allowance is applied per ad, so the same request can be fully served, partly served, or refused:
| Situation | What you get |
|---|---|
| Included ads left ≥ ads the job wants | 202 — every ad generated, nothing charged. |
| Some included ads left, fewer than the job wants | 202, then the job succeeds with fewer ads than it would otherwise have produced. There is no error, no warning field, and nothing in the result says the job was trimmed. Only the allowance is spent. |
| Zero included ads left and a card known to be absent | 402 insufficient-credits with reason: "no_payment_method", refused at submit before any work starts. |
resources + withheld in the job result against what you expected.Billing fields in the API
| Field | Where | Meaning |
|---|---|---|
| billable_count | POST /ads · GET /jobs/{job_id}/result | Ads in this job that incur a per-ad charge. 0 when every ad came out of the allowance, and 0 — not null — on a legacy-credits organization. It is null only on the 202 (the charge is not resolved yet), on a highlight job, and on succeeded_empty. |
| amount_cents | POST /ads · GET /jobs/{job_id}/result | Total charge in cents for those ads (billable_count × the per-ad price). Same rules as above, so 0 on a legacy-credits ad job. |
| withheld | GET /jobs/{job_id}/result | Ads this job produced whose media is not being served yet. Always empty on a legacy-credits or fully-paid job. |
| payment_status | GET /ads · GET /ads/{ad_id} | Per-ad charge state — see the table below. On a legacy-credits organization it is not_required, not null. |
| credits_reserved | POST /ads · POST /highlights | POST /ads: null on the current plans. POST /highlights: 0 on the current plans — the two differ, so branch on the endpoint, not on the plan. |
| credit_cost | GET /ads · GET /ads/{ad_id} | Legacy credit plans only, and even there it is null today: ad credit-debiting is switched off platform-wide. Read payment_status instead. |
Withheld media
An ad that generated successfully but has an unresolved charge is withheld: no download URL is minted for it, it does not appear in the job result’s resources, and its video_url is null on the ads endpoints. The ad itself is not lost — only its media is held back.
| payment_status | Served? | Meaning |
|---|---|---|
| not_required | yes | No charge applies — an included ad, a legacy-credits ad, or an Ad Polish copy. This is also the value a legacy-credits organization always sees. It can change to pending shortly after a job succeeds, as the charge is resolved. |
| paid | yes | The per-ad charge settled. |
| pending | withheld | The charge has not settled yet. Call /result again shortly. |
| failed | withheld | The charge was declined. Fix the payment method in the dashboard; the ad is served once it settles. |
{
"job_id": "job_…",
"status": "succeeded",
"resources": [],
"withheld": [
{ "resource_id": "…", "payment_status": "pending" }
],
"billable_count": 1,
"amount_cents": 2400,
"expires_at": null
}The job status is still succeeded in this case — withholding is a payment state, not a generation failure. expires_at is null because no signed URLs were minted.
When a trigger is refused
Payment refusals reach you on two different surfaces, and most of them are not the 402. Only one check runs before the call returns; the authoritative charge decision happens later, in the background, and surfaces as a failed job.
At submit — 402 insufficient-credits
| reason | When | What to do |
|---|---|---|
| no_payment_method | The only reason a pay-per-ad plan returns at submit. Zero included ads left and a card known to be absent. | Add a card in the dashboard. |
| org_balance | Legacy credit plans only: the organization’s credit balance is too low. | Top up credits. |
| workspace_cap | Legacy credit plans only: the workspace credit cap is too low. | Raise the cap in the dashboard. |
In the background — the job ends failed
The per-ad reserve runs after concepts are generated, so a refusal there cannot be returned from POST /ads. The call has already answered 202. The job later reaches failed, and error.code carries the reason:
| error.code | When | What to do |
|---|---|---|
| free_quota_exhausted | The included-ad allowance ran out while the job was running. | Add a card, or wait for the next period. |
| outstanding_balance | An unpaid charge is blocking new generation. | Settle it in the dashboard, then submit again with a NEW idempotency key. |
Not returned by this API
You may see these values elsewhere in VideoForce (they are part of a shared billing vocabulary), but no /public/v1 call produces them today: card_declined and authentication_required are raised only when buying a plan, and monthly_cap_exceeded is unreachable by design. Do not build branches that depend on them — but do fall through gracefully if one appears.
reason as a generic 402 — new values can be added within v1. A 503 is the opposite case: billing was unreachable, so retry after Retry-After rather than asking the customer for money.Legacy credit plans
Organizations on the retired Amplify and Dominate plans still bill in credits rather than per ad. They are not migrated, so an integration that serves multiple customers may see both models. On those organizations:
credits_reservedis an integer on the 202.credit_cost, however, staysnull: ad credit-debiting is switched off platform-wide, so legacy organizations are not charged credits for ads today.payment_statusisnot_requiredandbillable_count/amount_centsare0— notnull.withheldis always empty; media is never held back.POST /highlightsdoes cost credits: one per second of source video, minimum one.- A 402 carries
org_balanceorworkspace_cap.
A 409 mode-mismatch means a request took the wrong money path for the organization — usually a stale billing state right after a plan change. Retry shortly; if it persists, contact support.
Errors
Standard HTTP status codes. Failures from the API itself are RFC 9457 application/problem+json. Edge failures are not: a gateway-level per-IP rate limit, and 502/504 errors, return plain JSON with a different shape, so parse defensively rather than assuming type is present. The machine-readable identifier is the type URL's slug; include request_id when contacting support.
{
"type": "https://videoforce.ai/problems/video-not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "One or more input videos do not exist in the selected workspace.",
"instance": "/public/v1/highlights",
"request_id": "…#123",
"context": { "invalid_video_ids": ["…"] }
}Request-validation errors (422) additionally carry an errors array of { field, message }. Other 422s — such as idempotency-body-mismatch — do not; that one carries context.job_id instead. Every response also carries an X-Request-ID header, which matches request_id in the body and is the value to quote to support.
| Status | When it happens |
|---|---|
| 200 / 201 / 202 | Success. 201 = created; 202 = async job accepted. |
| 400 | Missing/invalid Idempotency-Key on a generation call, or workspace-selection-required — the key is attached to several workspaces and no X-Active-Workspace header was sent. |
| 401 | Missing, malformed, revoked, or expired API key (Invalid API key). |
| 402 | The generation cannot be paid for — the job is aborted and never billed. context.reason says why; see Billing & plans. |
| 403 | The key is valid but cannot act in the selected workspace — no-active-workspace-attachments or capability-not-granted-in-workspace. |
| 404 | Resource not found or not in your workspace (indistinguishable, by design). |
| 409 | Job not finished yet or failed/aborted (on /result), highlights already generated for that video, an idempotent retry (same key + body) is still in flight, or the organization’s billing mode does not permit the operation (mode-mismatch). |
| 422 | Request validation failed, or an Idempotency-Key was reused with a different body. |
| 429 | An organization rate-limit window is exhausted — see Rate limits. |
| 500 / 502 | internal-error or external-service-error — retry with backoff and a new idempotency key. |
| 503 | dependency-unavailable — a dependency is temporarily unavailable; retry after Retry-After seconds with a new idempotency key. |
Idempotency
Generation calls (POST /ads, POST /highlights) require an Idempotency-Key header — a unique value (e.g. a UUID) per logical request. It makes network retries safe and prevents duplicate jobs and double-billing.
| Case | Result |
|---|---|
| Header missing / empty / > 255 chars | 400 idempotency-key-required |
| Same key + same body — original still running | 409 idempotency-key-in-flight — back off and re-poll the job |
| Same key + same body — original reached any terminal state | Replays that original job (header Idempotent-Replayed: true) and returns its status — which may be aborted or failed, not queued. Nothing new is created or billed. |
| Same key + different body | 422 idempotency-body-mismatch |
aborted — which is terminal. Keys never expire, so re-sending that same key replays the aborted job forever, with Idempotent-Replayed: true and 202. It will keep doing so after the customer adds a payment card. The retry looks successful and no ad is ever generated. Always mint a fresh key once you have seen a response.Pagination
List endpoints paginate. Two styles, depending on the resource.
| Style | Used by | How |
|---|---|---|
| Cursor | projects, ads, highlights | Pass limit (1–100). Read has_more and next_cursor; pass next_cursor back as cursor for the next page. |
| Page | videos | Pass page (≥1) and page_size (1–100). Response includes total, page, page_size. |
Versioning
The API is versioned in the URL path (/public/v1). Backwards-incompatible changes ship under a new path segment (/public/v2); additive changes (new endpoints, new optional fields, new enum values) can appear within v1 without notice, so write tolerant clients that ignore unknown fields.
Changelog
Notable changes, newest first.
| Date | Change |
|---|---|
| 2026-10 | Changed Documentation correctness pass. The Idempotency-Key retry guidance, the 402 reason tables, the null-versus-zero rules for the billing fields, and the per-call cost of POST /ads were all wrong or missing — re-read those sections if you integrated before this date. No API behaviour changed. |
| 2026-10 | Added Billing & plans documentation: the Boost / Pro / Studio plans, per-ad pricing, withheld media, and the 402 reason vocabulary. |
| 2026-09 | Changed broll_video_ids on POST /ads is now optional — omit it or send an empty list to generate without B-roll. It had been required since 21 Aug 2026, so a client written in that window sends it unconditionally; that still works. |
| 2026-09 | Breaking Payment refusals after submit no longer surface as a 402. The job now ends failed with the reason in error.code (for example outstanding_balance). A client that only inspects the trigger response will misread these as generic failures. |
| 2026-08 | Added Pay-per-ad billing fields: billable_count and amount_cents on POST /ads and the job result, withheld on the job result, and payment_status on the ads endpoints. 409 mode-mismatch replaced an opaque 502. |
| 2026-08 | Breaking brief now requires four more fields: target_audience (free text), audience_age, audience_gender and tone. The last two are arrays (multi-select, at least one value). |
| 2026-08 | Changed video_ids on POST /ads accepts up to 20 source videos (was 10), with a combined 10-minute duration cap. |
| 2026-08 | Breaking POST /broll/upload added, and broll_video_ids became a required input on POST /ads. The synthetic_fallback and ai_voiceover_clips flags were removed — sending either now returns 422. |
| 2026-08 | Added Production environment (https://api.videoforce.ai) is now publicly available. |
| 2026-07 | Changed Per-organization concurrent-job limit raised from 2 to 5. |
| 2026-07 | Added Public API v1: projects, video upload, ad & highlight generation, async jobs, and result retrieval. |
Support
Need help integrating?
- Email support@videoforce.ai — include the
request_idfrom any error response so we can trace it. - Manage keys and workspaces in the VideoForce dashboard.