Skip to content
Last updated

Quickstart

Shuffll's API lets you create professional AI-generated videos programmatically. This guide walks you through getting your first video from a text prompt to a downloadable MP4 in a few API calls.

Prerequisites

  1. Create a Shuffll account at app.shuffll.com.
  2. Get your API key — navigate to Account Settings → API Key → Generate.
  3. Find your workspace ID — call GET /auth/organization/list and note the workspaceId from the workspace you want to use.

Keep your API key secure and never expose it in client-side code.

Authentication

Every request requires an x-api-key header:

-H "x-api-key: YOUR_API_KEY"

Step 1 — Create a project

Send a prompt and let Shuffll generate the script, visuals, and voiceover automatically. Set toAutoEnhance: true and toAutoExport: true so the full pipeline runs without any additional triggers. Add a webhook URL to receive a notification when the video is ready.

curl -X POST "https://api.shuffll.com/api/v1/auth/project/create" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "How AI is transforming the marketing industry",
    "language": "en",
    "videoLength": "medium",
    "toAutoEnhance": true,
    "toAutoExport": true,
    "webhook": "https://yourserver.com/webhooks/shuffll"
  }'

Response:

{ "projectId": "6947b539cc95ea68854bb523" }

Save the projectId — you will use it in every subsequent call.

Step 2 — Poll creation status

The AI takes a moment to build the script and generate scene visuals. Poll this endpoint until status is DONE.

curl "https://api.shuffll.com/api/v1/auth/project/6947b539cc95ea68854bb523/create/status" \
  -H "x-api-key: YOUR_API_KEY"

Possible responses:

{ "status": "STRUCTURE" }         // AI is building the storyline
{ "status": "GENERATING_IMAGES" } // Scene visuals are being created
{ "status": "DONE" }              // Ready — enhancement starts automatically

Recommended polling interval: every 5–10 seconds.

Step 3 — Poll enhancement status

Once creation is DONE, Shuffll automatically begins post-production (branding, subtitles, audio cleanup). A 202 response means it is still running; a 200 response means it is complete.

curl "https://api.shuffll.com/api/v1/auth/project/6947b539cc95ea68854bb523/edit/status/enhance" \
  -H "x-api-key: YOUR_API_KEY"

In progress (HTTP 202):

{ "percentages": 45, "isDone": false }

Complete (HTTP 200):

{ "percentages": 100, "isDone": true }

Step 4 — Poll export status (or use a webhook)

If you used toAutoExport: true, the export also runs automatically. Poll the export status endpoint — or skip polling entirely if you set a webhook.

curl "https://api.shuffll.com/api/v1/auth/project/6947b539cc95ea68854bb523/edit/status/export" \
  -H "x-api-key: YOUR_API_KEY"

In progress (HTTP 202):

{ "isDone": false }

Complete (HTTP 200):

{
  "isDone": true,
  "urls": {
    "uploadPath": "https://cdn.shuffll.com/.../video.mp4",
    "dashPath": "https://cdn.shuffll.com/.../manifest.mpd"
  }
}
  • uploadPath — direct MP4 download URL
  • dashPath — MPEG-DASH streaming manifest URL

Webhook alternative (no polling required)

If you set a webhook URL in Step 1, Shuffll calls it when the export is complete. Your server receives:

{
  "type": "export",
  "payload": {
    "projectId": "6947b539cc95ea68854bb523",
    "projectName": "How AI is transforming the marketing industry",
    "urls": {
      "uploadPath": "https://cdn.shuffll.com/.../video.mp4",
      "dashPath": "https://cdn.shuffll.com/.../manifest.mpd"
    },
    "additionalParams": {}
  }
}

Use additionalParams in your create request to embed any custom metadata (e.g., a user ID or order ID) that you want returned in the webhook payload.

Next steps

 
Next page