API reference

Create a project from a link

curl -X POST $BASE/projects \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"url":"https://youtube.com/watch?v=…","language":"en",
       "settings":{"maxClips":10,"aspects":["9:16","1:1"],"platforms":["instagram_reels"]}}'
→ 201 {"id":"…","status":"queued"}

Upload a file

curl -X POST "$BASE/projects?title=Episode%2012&language=en" \
  -H "Authorization: Bearer $KEY" -H "content-type: video/mp4" --data-binary @episode.mp4

Get status and clips

GET $BASE/projects/{id}
→ {"status":"ready","clips":[{"id":"…","title":"…","hook":"…","virality_score":82.4,
     "sub_scores":{"hook":90,"flow":76,"value":71,"trend":64},"reason":"…",
     "cost":{"totalInr":0.42,…},
     "renders":[{"id":"…","aspect":"9:16","status":"done","download_url":"/api/v1/renders/…/download"}]}]}

Render another version (free)

POST $BASE/clips/{id}/render  {"aspect":"1:1","platform":"linkedin","layout":"fit"}

Schedule a post

POST $BASE/posts  {"render_id":"…","account_ids":["…","…"],"caption":"…","when":"2026-11-01T18:30:00+05:30"}
→ 201 {"posts":[{"id":"…","platform":"youtube","scheduled_at":"…","status":"scheduled"}]}
# leave out "when" to use each platform's best hour; GET $BASE/posts lists them

Other endpoints

• GET /projects — list projects
• GET /renders/{id}/download — MP4 (supports Range)
• GET /usage — plan, minutes used and left
• GET /api/projects/{id}/transcript?format=srt|vtt|txt|json
• GET /api/clips/{id}/export?format=xml|srt|vtt

Webhooks

Events: project.ready, project.failed, clip.rendered, post.published, post.failed. Each POST carries x-surge-signature: sha256=HMAC(secret, timestamp + "." + body) and x-surge-timestamp. Failed deliveries retry 5 times.

// Node verification
const sig = crypto.createHmac("sha256", SECRET).update(`${req.headers["x-surge-timestamp"]}.${rawBody}`).digest("hex");
if ("sha256=" + sig !== req.headers["x-surge-signature"]) return res.status(401).end();