REST API reference

Base URL: https://second.studio.hellofaro.io · All bodies are JSON · Authenticate every /v1 request with

Authorization: Bearer ss_live_...

Conventions

• Jobs are asynchronous. Endpoints that do work (/v1/styles, /v1/edits, /v1/recordings, /v1/fetch) return 202 with a job immediately. Poll GET /v1/jobs/{id} every few seconds.
• Credits are charged when a job is accepted and refunded automatically if it fails. See Credits.
• Getting a key: get started. Keys work only after a person approves the account; an unapproved key gets 403 key_pending_approval.
• Errors have one shape:

{ "error": { "code": "insufficient_credits", "message": "this costs 5 credit(s); balance is 2. …" } }

Account

GET /v1/me

{ "orgId": "js7…", "keyScope": "agent", "name": "Acme", "credits": 93, "autoPublish": false,
  "allowHostedFetch": false, "maxConcurrentJobs": 4, "apiVersion": "2026-10-08" }

`apiVersion` changes whenever the endpoint or MCP tool surface changes; MCP clients that cache the tool
list should reconnect when it does.

DELETE /v1/account

Deletes the signed-in person's own account. This is the endpoint the mobile app's Delete account button calls. Authenticate with either:

• an API key (Authorization: Bearer ss_live_...) owned by a member who is linked to a signed-up person. The account deleted is that person's. Account-level keys (no member) get 403 no_user_for_key and nothing changes.
• the person's Clerk session token (Authorization: Bearer <Clerk session JWT>).

curl -X DELETE https://second.studio.hellofaro.io/v1/account \
  -H "Authorization: Bearer $SECOND_STUDIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"confirm":"DELETE"}'

{ "deleted": true, "clerkDeleted": true, "memberships": 1, "orgsClosed": 1, "keysRevoked": 2 }

It removes the person from every account they belong to, revokes every API key they own (including the one used), writes account.deleted to each account's audit log, anonymizes their profile and deletes their sign-in. From a Convex client the same thing is api.account.deleteMe({ confirm: "DELETE" }).

If you are the only member of an account, that account is closed and all of its keys are revoked. Unused credits are not refunded.

Assets

An asset is any file in your account: an uploaded clip or song, a reference, a finished edit, a recording. Uploading takes three calls, so large files go straight to storage instead of through the API.

POST /v1/assets/upload-url

Returns a one-time URL: { "uploadUrl": "https://…" }. Send the raw bytes to it:

curl -X POST "$uploadUrl" -H "Content-Type: video/mp4" --data-binary @clip.mp4
# → { "storageId": "kg2…" }

POST /v1/assets

Register the upload: { "storageId": "kg2…", "filename": "clip.mp4" } → 201 with the asset:

{ "id": "j97…", "kind": "video", "role": "upload", "filename": "clip.mp4", "contentType": "video/mp4",
  "size": 991017, "url": "https://…", "source": null, "jobId": null, "createdAt": 1791328110667 }

kind is video, audio, image, json or other, from the uploaded Content-Type.

GET /v1/assets · GET /v1/assets/{id} · DELETE /v1/assets/{id}

List the 100 most recent, read one (with a download url), or delete one and its file permanently.

Styles

POST /v1/styles: analyze a reference (2 credits for the first minute, then 1 per extra minute, 10 minutes max)

{ "assetId": "j97…", "semantic": true }

semantic (default true) adds vision-model shot roles, descriptions and caption style on top of the measured analysis. When the job succeeds, result.styleId is the new style and result summarizes it:

{ "styleId": "jn7…", "aspect": "9:16", "duration": 17.8, "shot_count": 7, "bpm": 99.4,
  "cuts_on_beat_ratio": 0.71, "semantic": true, "summary": "Fast result-first hook, …",
  "pacing": { "shot_count": 7, "mean_shot": 2.54, "median_shot": 0.73, "cuts_per_minute": 20.3, … } }

GET /v1/styles · GET /v1/styles/{id}

GET /v1/styles/{id} includes the full spec: see Styles and edits.

Edits

POST /v1/edits: cut your clips to a style (5 credits plus 1 per started minute of footage)

The finished job's outputs contain the edit (mp4) and the plan (JSON: which clip and in-point filled each shot). result.qa is the automatic quality report; result.notes explains decisions such as beat snapping and layout.

Generation

See Generating images, characters and video for every option.

Generation results include notes on choices made. The production craft behind them stays server-side.

Models, skills, swaps, edits

See Generation.

Explainer videos

Brand kits, scripts and renders have their own page: Explainer videos.

Recordings

POST /v1/recordings: record a public web app (3 credits)

{ "url": "https://example.com", "viewport": "mobile",
  "steps": [ { "type": "hold", "seconds": 2 }, { "type": "click", "selector": "text=Pricing" },
             { "type": "scroll", "pixels": 900 }, { "type": "hold", "seconds": 2 } ] }

See Recording for every step type. Output: a recording asset (mp4) and result.marks, the timestamp of every step for cutting.

POST /v1/repo-recordings: record a private GitHub repository (20 credits, up to 3 flows)

{ "repo": "acme/web", "ref": "main", "maxFlows": 3 }. Builds the app in a sandbox and records its key flows; needs GitHub connected (POST /v1/github/install). Optional envSetId (/v1/env-sets), loginId (/v1/logins), storageState or storageStateAssetId, flows, mode. Using an env set, login or session needs an admin key; repo must belong to the installation's GitHub account. Returns 503 github_not_configured until GitHub is switched on. Price: 4 credits per flow past 3, 3 more with a saved login or storage_state, and 5 credits per started 10 sandbox minutes past 25, charged at completion (hard stop at 45 minutes). See Recording.

Fetching

POST /v1/fetch: a reference from a social URL (1 credit)

{ "url": "https://www.tiktok.com/@…/video/…", "start": 3, "end": 18 }. url must be a public http or https address. Private hosts, link-local and metadata addresses (including IPv4-mapped IPv6), and other schemes are rejected with 400 invalid_url. start/end (seconds, optional) keep only that section: handy for a 4–30 s reference clip for POST /v1/videos. Hosted fetching is a per-account setting: if it is off you get 403 fetch_disabled. Ask us to enable it (POST /v1/reports works) and confirm you have the rights to the clips, or download it on your own machine and upload it instead. Output: a fetched asset with source attribution (and the trim applied).

Optional "then": "analyze_style" | "remix" | "none" starts the next step on the server as soon as the fetch succeeds, so the caller does not have to stay connected. Both analyze_style and remix start a style analysis of the fetched clip, charged like POST /v1/styles (2 credits for the first minute) when it starts; for remix, use the resulting styleId with your own clips or character. The fetch job's result.followUp holds { "then", "jobId" } (or { "then", "error" }, e.g. insufficient_credits, if it could not start), and the follow-up job's input.fromJobId points back at the fetch.

Templates

Social videos saved to replicate later, from the mobile app's share sheet or by your agent.

POST /v1/templates: save a template (free)

{ "url": "https://www.tiktok.com/@…/video/…", "title": "Hook style", "note": "Copy the fast cuts", "analyze": true }. Only url is required, and it has the same public http(s) rules as POST /v1/fetch. analyze: true also fetches the video and learns its style, charged like POST /v1/fetch with then: "analyze_style"; if hosted fetching is off the template is still saved and the response includes analyzeError.

GET /v1/templates · GET /v1/templates/{id} · DELETE /v1/templates/{id}

Each template has id, url, platform, title, note, status (saved, analyzing, ready, failed) and styleId once ready. To replicate one: use styleId with POST /v1/edits, or, if there is none yet, POST /v1/fetch its url with then: "analyze_style".

Jobs

GET /v1/jobs/{id} · GET /v1/jobs

{ "id": "jd7…", "kind": "replicate", "status": "succeeded", "progress": "done", "error": null,
  "result": { … }, "creditsCharged": 5, "refunded": false, "attempts": 1,
  "outputs": [ { "assetId": "j95…", "role": "edit", "kind": "video", "filename": "edit.mp4", "url": "https://…" } ],
  "createdAt": 1791469255706, "startedAt": 1791469256012, "finishedAt": 1791469281420 }

status: queued → running → succeeded | failed. A job with no word from the worker for three hours is marked failed and refunded.

Social accounts and posts

See Posting for the approval model.

POST /v1/posts:

{ "assetId": "j95…", "caption": "Dinner in one search #recipes",
  "targets": [ { "platform": "tiktok", "accountId": "6a62…" } ],
  "scheduledFor": "2026-10-12T18:00:00-04:00" }

Give scheduledFor (ISO 8601 with an offset, or with timezone) or "publishNow": true. Post statuses: pending_approval → approved → scheduled | published | failed, or rejected.

Team

Members, roles (admin, manager, creator, reviewer), keys, per-person credit caps and the shared library have their own page: Team. Teams (with invites) and budgets (with key caps) are separate switches, on for accounts created from now on; older accounts keep their behavior until we enable them, and until then those endpoints answer 403 governance_disabled.

Reporting problems

Found a bug, want a feature, or have a question? File it through the API: agents can do this on their own when something goes wrong. Reports are free.

POST /v1/reports

{ "kind": "bug", "severity": "high", "jobId": "jd7…",
  "title": "Captions cut off on 4:5 edits",
  "description": "The second caption line is clipped at the top. Expected it inside the frame." }

Returns 201 with the report. GET /v1/reports and GET /v1/reports/{id} show each report's status (open, acknowledged, fixed, wont_fix or closed) and the team's response.

POST /v1/feedback

Send product feedback: what to fix, add or keep. Free (0 credits), limited to 10 per hour per key. The MCP feedback tool and the /feedback prompt use this route.

{ "message": "Let me pick the caption font per edit.", "category": "feature" }

Returns 201 with { "id": "...", "message": "Thank you for the feedback. ..." }.

Credits

Agents: this page is also available as Markdown; the whole reference is in llms-full.txt.