Programmatic generations,
same pipeline as Studio

Overview

Provision API keys from your Automate subscription and list them in ZOVGEN_API_KEYS on the server (comma-separated). Each request to /api/v1/* must include a valid key.

Optional subscription check: set ZOVGEN_API_ENFORCE_SUBSCRIPTION=true and map keys to internal user UUIDs with ZOVGEN_API_KEY_USERS=key=user-uuid,.... The linked account must have plan automate and an active or trialing subscription (synced via Lemon webhooks when checkout email matches the ZovGen account email). Otherwise the API returns 403.

Two surfaces: (1) /api/v1/* with an API key for scripts and integrations. (2) /api/jobs, /api/me/* with a logged-in browser session (same as the web app). Scheduled publishing and OAuth token refresh run on the server; they are not exposed as separate public routes.

Automate API authentication

Use either header style:

X-ZovGen-Key: sk_your_key_here

# or

Authorization: Bearer sk_your_key_here

Missing or invalid keys return 401. If keys are not configured on the server, the API returns 503. With subscription enforcement on, inactive or non-Automate accounts return 403.

Create a job

POST /api/v1/jobs
Content-Type: application/json
X-ZovGen-Key: sk_live_xxx

{
  "url": "https://apps.apple.com/app/your-app/id123",
  "language": "en",
  "pipeline": "slideshow",
  "targets": ["youtube_shorts"],
  "subtitle_style": "clean_white"
}

pipeline is slideshow or video. The response includes job_id and initial status.

Poll status

GET /api/v1/jobs/{job_id}
X-ZovGen-Key: sk_live_xxx

When status is completed, use video_url and slideshow_zip_url from the JSON. They are relative to your ZovGen origin.

Browser session API (cookie auth)

These routes mirror Studio behavior. Send requests with the same session cookie your browser gets after login (or use the UI). Common paths:

• GET /api/auth/me — session user, plan, and monthly usage. The usage object includes generations_this_month, quota_monthly (0 = unlimited), weak_performance_refunds_this_month (extra slots from low-reach credits), and effective_quota_monthly (quota_monthly + refunds when capped).
• GET/POST /api/jobs, GET/PATCH /api/jobs/{id}, POST /api/jobs/{id}/publish
• GET/PATCH /api/me/studio-preferences — sources, generation defaults, auto-publish flags, platform weights.
• GET /api/me/publish-calendar — upcoming scheduled posts.
• GET /api/me/social-accounts — connected YouTube, TikTok, Meta.

Full schemas appear in /api/docs when routes are listed there; otherwise infer from the OpenAPI spec generated by the backend.

Public endpoints (no key)

GET /api/config/public — feature flags and client-safe config for the marketing site and app shell.

Marketing blog (read-only)

US English articles generated on a schedule. Use these for RSS, SEO, or integrations. No authentication.

GET /api/public/blog/posts
GET /api/public/blog/posts/{slug}
GET /api/public/blog/feed.xml
GET /api/public/blog/sitemap.xml

Human-readable hub: /blog.

OpenAPI & try-it console

The backend exposes Swagger UI at /api/docs. Use it to inspect schemas and test calls against your environment.