ClipCard API

Base URL: https://api.clipcard.app (locally http://localhost:8080). All request and response bodies are JSON unless noted.

Developers authenticate with an API key and pay in credits (see API keys and credits). The web app's visitors are free and limited per IP address, unless its session cookie says who they are (see Accounts).

Quick start

Create a key on your account page, then:

curl -X POST https://api.clipcard.app/v1/images \
  -H "X-API-Key: cc_live_…" -H "Content-Type: application/json" \
  -d '{"url": "https://x.com/user/status/1840000000000000001", "theme": "dark"}' \
  -o card.png

Videos run as jobs: POST /v1/videos answers 202 with a job to poll at GET /v1/jobs/{id}, or pass webhookUrl to be told when it finishes.

Platforms

Every endpoint that takes a url accepts X posts (x.com, twitter.com and their mirrors) and TikTok posts (tiktok.com/@user/video/… and tiktok.com/@user/photo/… slideshows, and the vm.tiktok.com, vt.tiktok.com and tiktok.com/t/… short links). A bare numeric tweetId always means an X post.

Posts carry "platform": "x" or "platform": "tiktok". TikTok posts can be downloaded (/v1/downloads): the original MP4 without TikTok's watermark, the sound alone, or a slideshow's photos (see Download outputs). TikTok posts also carry a sound (title, author, url, durationMs) and TikTok's metrics.views and metrics.shares. Images and videos of TikTok posts are drawn as TikTok-styled cards: bold hashtags, the sound's name under the media, and views, likes, comments and shares. Every TikTok job fetches the post afresh, because TikTok's media links expire within hours.

Endpoints

Render request

POST /v1/images, /v1/videos and /v1/downloads take the same body. Only url (or tweetId) is required.

{
  "url": "https://x.com/user/status/1840000000000000001",
  "format": "9x16",
  "theme": "dark",
  "background": "midnight",
  "show": { "metrics": true, "date": true, "verified": true, "quote": true },
  "media": { "from": "post", "index": 0 },
  "grid": false,
  "timeZone": "Africa/Nairobi",
  "quality": "hd",
  "webhookUrl": "https://example.com/clipcard-hook"
}

Identical requests within 24 hours return the same job and file.

Download outputs

output picks what /v1/downloads makes. Every output costs the same, one daily render or 2 credits.

A post without the asked-for output answers no_video, no_audio or no_photos. The post's text, author, date and counts come from GET /v1/posts, not the download.

API keys and credits

Create keys on the account page (your email address must be confirmed first; up to 10 keys). A key is shown once: store it like a password, and call the API from your server only. Browsers cannot send keys, since the API does not allow the header across sites. Send it on every request:

X-API-Key: cc_live_…

Keys work on /v1/posts, /v1/tweets, /v1/images, /v1/videos, /v1/downloads, /v1/jobs/{id} and GET /v1/account. A missing key makes the request a free visitor's; a wrong or revoked key answers 401 invalid_api_key.

Every key request gets the best quality up to 1080p, no watermark and videos up to 10 minutes, and pays in credits instead of counting against a daily limit:

• A request is charged once it passes every check (bad input costs nothing), and the balance after it comes back in X-Credits-Remaining.
• A job that fails is refunded automatically, within a few seconds, whether or not you poll it.
• Asking again for a render you already paid for, within 24 hours, returns the same job at no charge, so retrying after a timeout is safe. A render cached from someone else's request costs the usual credits.
• Without enough credits the request answers 402 insufficient_credits.
• New accounts get 50 credits once; API plans add their monthly credits.
• Each key may make 10 requests a second. Over that answers 429 rate_limited with a Retry-After header in seconds.

GET /v1/account:

{
  "user": { "id": "12", "email": "[email protected]", "name": "Ann" },
  "plan": { "id": "api_starter", "name": "API Starter", "kind": "api", "endsAt": "…" },
  "credits": 487,
  "costs": { "image": 1, "video": 5, "download": 2 },
  "rateLimit": { "perSecond": 10 }
}

Webhooks

Pass webhookUrl with a render and ClipCard sends a POST there when the job finishes, done or failed. The URL must be https on a public host. If you ask again for the same render with a new webhookUrl, that URL is called too.

{
  "id": "evt_q3m7…",
  "type": "job.done",
  "createdAt": "2026-09-30T19:05:08Z",
  "job": { "id": "job_k3v7q2m…", "type": "video", "status": "done", "download": { "url": "…" } }
}

type is job.done or job.failed; job is the same object as GET /v1/jobs/{id} returns. Answer with any 2xx status within 10 seconds. Anything else (including redirects) is retried 5 times, after 10 seconds, 1 minute, 5 minutes, 30 minutes and 2 hours. The same event can arrive more than once: use id (also in the ClipCard-Event-Id header) to ignore repeats. The account page lists recent calls and their errors.

Each call is signed with your account's webhook secret (whsec_…, on the account page):

ClipCard-Signature: t=1727723108,v1=5257a869e7…

v1 is the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the secret. To check a call, compute it over the body exactly as received, compare in constant time, and reject timestamps more than 5 minutes old. In Node:

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
  const want = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  return parts.v1?.length === want.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(want))
}

Making a new secret on the account page takes effect at once, including for calls still being retried.

Jobs

{
  "job": {
    "id": "job_k3v7q2m…",
    "type": "video",
    "status": "done",
    "progress": 100,
    "createdAt": "2026-09-30T19:05:01Z",
    "finishedAt": "2026-09-30T19:05:07Z",
    "download": {
      "url": "https://….r2.cloudflarestorage.com/clipcard-files/2026/09/30/job_k3v7q2m….mp4?X-Amz-…",
      "previewUrl": "https://….r2.cloudflarestorage.com/clipcard-files/2026/09/30/job_k3v7q2m….mp4?X-Amz-…",
      "filename": "clipcard-1840000000000000001-video.mp4",
      "contentType": "video/mp4",
      "bytes": 444111,
      "expiresAt": "2026-10-01T19:05:01Z"
    }
  }
}

status is queued, running, done, failed or expired (the file was deleted after 24 hours). Poll every second or two until done or failed.

url saves the file under filename; previewUrl (images and videos only) shows it in the browser, for <img> and <video> tags. Both are signed, expire at expiresAt and must be used exactly as given: changing any part breaks the signature. They point at Cloudflare R2, which serves the file directly; a self-hosted install without R2 serves them from the API's /files/ path instead. Download links support HTTP range requests, so videos can seek.

Limits

API keys pay in credits instead; see above. The rest of this section is about the web app.

Free requests are limited per IP address per UTC day (10 by default), whether or not the caller is signed in. A signed-in user with a plan skips the bot check and has a per-user fair-use cap instead (500 a day by default), videos up to 10 minutes, and no watermark. Every render response carries:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset (Unix time of the next reset)

Requests rejected for bad input do not count. A job that fails on our side is refunded the first time its failed status is read.

Accounts

These routes serve the web app. Signing in sets clipcard_session, an HttpOnly, SameSite=Lax cookie on the API's host, valid for 30 days and extended while in use. The web app and API share a parent domain, so the browser sends it with credentials: "include". State-changing requests count the cookie only when their Origin is the web app; /v1/auth/* and /v1/account/* refuse other origins with bad_origin.

Without a database (CLIPCARD_DATABASE_URL unset) the API runs with accounts off: /v1/me reports accounts.enabled: false and these routes answer accounts_disabled.

A payment buys one month or one year of a plan; plans never renew on their own. Buying the plan you have adds the time to the end of it; buying another replaces it from that day. An API plan's credits arrive with the payment (twelve months' worth for a year). Paystack returns the browser to the web app's /billing/return?reference=…, which calls confirm; Paystack's webhook (POST /v1/billing/paystack/webhook, signed) applies the payment too, so it counts even if the browser never comes back. Without Paystack configured these routes answer billing_disabled.

The admin dashboard's routes (/v1/admin/*) answer only users with the admin role and are not part of the public API.

All sign-in methods share one account per email address. Google and GitHub must report the address as verified. An account made with a password whose address was never confirmed belongs to whoever later proves the address (by Google, GitHub or an emailed link): its password is removed and its sessions end, so nobody can claim someone else's email ahead of them.

GET /v1/me works for everyone:

{
  "user": { "id": "12", "email": "[email protected]", "emailVerified": true, "name": "Ann", "role": "user",
            "createdAt": "…", "signInMethods": ["google", "password"] },
  "plan": { "id": "pro", "name": "Pro", "kind": "pro", "endsAt": "…" },
  "credits": 50,
  "limits": { "quality": "hd", "watermark": false, "maxVideoSeconds": 600,
              "dailyLimit": 500, "remaining": 498, "resetAt": "…" },
  "accounts": { "enabled": true, "methods": ["google", "github", "email", "password"] },
  "billing": { "enabled": true, "currency": "USD" }
}

user, plan and credits are absent or null for visitors and free users. GET /v1/history returns {"jobs": [...]}: each is a job plus requestedAt, tweet (id, author, text) and the render settings. Jobs whose files are gone show status: "expired".

Errors

Every error has the same shape:

{ "error": { "code": "video_too_long", "message": "This video is 5m00s; the limit on this plan is 2m00s." } }