Skip to content
InstaStudio

API reference

Base URL https://studio.instadatahelp.com/api/v1. Authenticate with Authorization: Bearer is_live_… (create keys in Studio → API & Developers; Max and Team plans). All costs are in your workspace credits — the same transparent prices as the app.

Models

GET /models lists every model with its tools, inputs, parameters and an example credit cost. Use "model":"auto" to let the media router pick the best value model for your quality (budget | standard | premium).

Upload inputs

curl https://studio.instadatahelp.com/api/v1/uploads -H "Authorization: Bearer $KEY" -F file=@photo.jpg
# or
curl https://studio.instadatahelp.com/api/v1/uploads -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"url":"https://…/photo.jpg"}'
→ {"id":"<asset-id>","type":"image"}

Create a generation

POST https://studio.instadatahelp.com/api/v1/generations
{
  "tool": "video",                 // omit for Auto: we infer image / video / speech / music…
  "model": "auto",                 // or a model id from /models, e.g. "veo-3.1-fast"
  "quality": "standard",
  "prompt": "Slow dolly-in on @Priya pouring chai at dawn",   // @Name = your saved character
  "params": { "duration": 8, "aspect_ratio": "9:16", "generate_audio": true },
  "attachments": [{ "assetId": "<id>", "role": "image" }],    // roles: image | end | video | audio | mask
  "webhook_url": "https://your.app/hooks/instastudio"
}
→ 202 { "id": "…", "status": "queued", "credits": 120, … }

POST /estimate takes the same body and returns the credit cost without running it.

Get a generation

GET https://studio.instadatahelp.com/api/v1/generations/{id}
→ { "id", "status": "queued|running|succeeded|failed|canceled|awaiting_approval", "progress": 0-100,
    "credits", "outputs": [{ "type": "video", "url": "https://…/media/….mp4", "thumbnail_url", "width", "height", "duration_s" }],
    "text", "error": { "kind", "message" } }

Failed generations are refunded automatically. Poll every few seconds or use webhooks.

Agents (multi-scene, explainer, avatar shorts)

POST https://studio.instadatahelp.com/api/v1/agents  { "kind": "explainer", "topic": "How UPI works", "durationS": 60, "style": "2d", "voice": "eleven:Rachel" }
POST https://studio.instadatahelp.com/api/v1/agents  { "kind": "story", "prompt": "…", "scenes": 4, "aspect": "16:9" }
POST https://studio.instadatahelp.com/api/v1/agents  { "kind": "short", "avatarId": "…", "template": "selfie-review", "productId": "…" }
→ status "awaiting_approval" with "plan" and "estimate_credits" (webhook: generation.awaiting_approval)
POST https://studio.instadatahelp.com/api/v1/agents/{id}/approve   → starts generation; unused credits are returned at the end

Webhooks

We POST {"type":"generation.succeeded","data":{…same as GET…}} to your webhook_url with headers X-InstaStudio-Timestamp and X-InstaStudio-Signature: sha256=…, where the signature is HMAC-SHA256 of timestamp + "." + rawBody using your workspace signing secret.

import crypto from "node:crypto";
const ok = crypto.timingSafeEqual(
  Buffer.from(req.headers["x-instastudio-signature"].slice(7), "hex"),
  crypto.createHmac("sha256", SECRET).update(ts + "." + rawBody).digest());

Account & limits

GET /account returns plan and credit balance. Rate limit: 120 requests/minute per workspace. Errors are JSON {"error":{"code","message"}} with HTTP 400/401/402 (credits or plan)/404/409/429.

API reference · InstaStudio