The first step in Shuffll's pipeline is creating a project. A project represents a single video — its script, scene structure, media, voiceover, and settings. Once created, Shuffll automatically begins enhancement and, if configured, export.
- You call
POST /auth/project/createwith a prompt (or link, script, etc.). - Shuffll's AI generates a structured script divided into scenes.
- Visuals are assembled for each scene using the media fallback system.
- The project enters enhancement automatically.
The promptType field controls what Shuffll treats the prompt value as:
promptType | What Shuffll does |
|---|---|
Prompt (default) | Treats prompt as a free-text topic description and generates a full script |
Link | Scrapes the public URL provided in prompt and bases the script on that content |
Docs | Reads the Google Doc at the URL in prompt |
Slides | Reads the Google Slides presentation at the URL in prompt |
Script | Uses prompt as the final script verbatim — no AI script generation |
Create a short marketing video from a text prompt with full automation:
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": "Why our SaaS product saves marketing teams 10 hours a week",
"promptType": "Prompt",
"language": "en",
"videoLength": "medium",
"toAutoEnhance": true,
"toAutoExport": true,
"webhook": "https://yourserver.com/webhooks/shuffll"
}'Response:
{ "projectId": "6947b539cc95ea68854bb523" }| Field | Type | Description |
|---|---|---|
prompt | string | The input text, URL, or script |
promptType | string | One of Prompt, Link, Docs, Slides, Script |
language | string | Output language code, e.g. en, es, fr. Use auto to detect from the prompt |
videoLength | string | short (~60s), medium (~90s), long (~120s) |
storyTellingTechnique | string | Technique ID from GET /auth/config/storytelling_techniques |
toneOfVoice | string | Tone ID from GET /auth/config/tone_of_voice |
videoTagId | string | Category ID from GET /auth/config/video_tags |
toAutoEnhance | boolean | If true, enhancement starts automatically after creation |
toAutoExport | boolean | If true, export runs automatically after enhancement |
webhook | string (URL) | Receives a POST when the export completes |
additionalParams | object | Any custom metadata to echo back in the webhook payload |
To set a specific AI voice, retrieve options from GET /auth/config/ai_voice_options and pass the voice ID:
"aiVoiceSettings": {
"voiceId": "voice_abc123",
"voiceType": "openai",
"voiceInstructions": "Speak enthusiastically and clearly"
}To use an AI avatar presenter, retrieve options from GET /auth/config/ai_avatar_options:
"aiAvatarSettings": {
"avatarId": "avatar_xyz789"
}To use a specific template for scene structure and visual style, add a customTemplate object:
"customTemplate": {
"id": "template_id_here",
"flexibilityOverride": "minor"
}See Using Templates for the full guide on template customization options.
After creating a project, poll until status is DONE:
curl "https://api.shuffll.com/api/v1/auth/project/6947b539cc95ea68854bb523/create/status" \
-H "x-api-key: YOUR_API_KEY"status value | Meaning |
|---|---|
STRUCTURE | Building the storyline and script |
GENERATING_IMAGES | Generating scene visuals |
DONE | Creation complete — enhancement begins automatically |
Recommended polling interval: every 5–10 seconds.