# Create project

Create a new AI-powered video project from a prompt, URL, or script.

---

### Prompt Types

| promptType | Description |
|---|---|
| Prompt | A free-text description of the video topic (default) |
| Link | A public URL — Shuffll scrapes the content and uses it as the basis for the script |
| Docs | A Google Docs URL — Shuffll reads the document content |
| Slides | A Google Slides URL — Shuffll reads the slide content |
| Script | A pre-written script — AI generation is skipped, the script is used as-is |

---

### Scene Media — Fallback System

For each scene, Shuffll fills in media content using the following priority order.
If a source doesn't yield results, it automatically tries the next one.

1. Your videos (customTemplate.scenes[].videosToAdd) — Videos you explicitly provide are always used first.
2. Stock footage — Shuffll searches stock video libraries for footage matching the scene content.
3. Workspace assets — Shuffll looks in your workspace asset library for relevant clips.
4. Image → Video animation — A still image is generated (via Stability AI) and animated into a short clip.
5. AI video generation — A full video clip is generated from scratch based on the scene script.

You can override this default order using videoSourcesPipeline. For example, to use only workspace assets and then generate from text, set:
json
"videoSourcesPipeline": ["workspace_assets", "generate_from_text"]


The same fallback logic applies to still images in scene overlays, controlled by imagesSourcePipeline.

---

### Missing Images (toGenerateMissingImages)

Scene templates can have image slots in their dynamic values. If you don't fill those slots:
- toGenerateMissingImages: true → Shuffll generates a contextually relevant image using Stability AI.
- toGenerateMissingImages: false → The slot is left empty (scene renders without the image).

---

### AI Presenter (Avatar)

Set aiAvatarSettings.avatarId to use an AI avatar presenter in the video. Get available avatars from GET /auth/config/ai_avatar_options.

---

### Webhooks

Set webhook to a URL that Shuffll will call when the export completes. The payload sent to your URL will be:

json
{
  "type": "export",
  "payload": {
    "projectId": "...",
    "projectName": "...",
    "urls": { "uploadPath": "...", "dashPath": "..." },
    "additionalParams": { }
  }
}


Use additionalParams to embed any custom data (IDs, metadata) you want returned in the webhook payload.

Set toAutoEnhance: true and toAutoExport: true to fully automate the pipeline: create → enhance → export → webhook, with no polling required.

---

### After creating a project

Project creation is asynchronous. Poll GET /auth/project/{projectId}/create/status until the project is ready.
Enhancement runs automatically. Monitor progress with GET /auth/project/{projectId}/edit/status/enhance.
When enhancement is complete, trigger export with POST /auth/project/{projectId}/edit/export.

Endpoint: POST /auth/project/create
Version: 1.2.0
Security: ShuffllApiKey

## Request fields (application/json):

  - `prompt` (string, required)
    The content/topic for your video
    Example: "Explore Riot Games' Innovative Player Experiences"

  - `promptType` (string)
    How Shuffll should interpret the prompt field.
- Prompt — Free-text topic description (default)
- Link — A public URL; Shuffll scrapes the page content
- Docs — A Google Docs URL; Shuffll reads the document
- Slides — A Google Slides URL; Shuffll reads the slides
- Script — A fully written script; AI script generation is skipped
    Enum: "Prompt", "Link", "Docs", "Slides", "Script"

  - `language` (string)
    Language for the video script and voiceover.
Use auto to detect the language automatically from the prompt text.
Defaults to en when omitted.
    Enum: "auto", "en", "es", "fr", "zh", "iw"

  - `videoLength` (number)
    Target video duration in minutes.
0.5 → ~30 sec · 1 → ~1 min · 2 → ~2 min · 3 → ~3 min
    Enum: 0.5, 1, 2, 3

  - `storyTellingTechnique` (string)
    Storytelling structure for the script. Use the technique value from GET /auth/config/storytelling_techniques.
    Example: "The Before-and-After Transformation"

  - `toneOfVoice` (string)
    Narration tone. Use the id value from GET /auth/config/tone_of_voice.
    Enum: "Natural", "Professional", "Informative", "Inspirational", "Energetic"

  - `videoTagId` (string)
    Video category. Guides the AI when writing the script and selecting media.
Use the id value from GET /auth/config/video_tags. Defaults to explainer if omitted.
    Example: "Marketing"

  - `webhook` (string)
    URL to POST to when the project export completes.
See the endpoint description for the full webhook payload format.
    Example: "https://your-app.com/hooks/shuffll-export"

  - `additionalParams` (object)
    Arbitrary data to embed in the webhook payload (e.g., campaign ID, user ID).
    Example: {"campaignId":"camp_123","userId":"usr_456"}

  - `toAutoEnhance` (boolean)
    Automatically start enhancement after project creation completes.
Defaults to true for integration API requests.
    Example: true

  - `toAutoExport` (boolean)
    Automatically start export after enhancement completes.
Combine with webhook to receive the result with no polling required.

  - `aiVoiceSettings` (object)
    AI voiceover configuration. Get available voices from GET /auth/config/ai_voice_options.

  - `aiVoiceSettings.voiceId` (string)
    Voice identifier. Use the id value from GET /auth/config/ai_voice_options.
    Example: "alloy"

  - `aiVoiceSettings.voiceType` (string)
    Voice provider. Must match the voiceType of the chosen voice.
    Enum: "open-ai", "eleven-labs"

  - `aiVoiceSettings.voiceSpeed` (number)
    Playback speed multiplier (0.7–1.2). 1.0 is normal speed.
    Example: 1

  - `aiVoiceSettings.voiceInstructions` (string)
    Custom style instructions for the voice model (OpenAI voices only).
Overrides the global tone setting for fine-grained voice control.
    Example: "Speak slowly and clearly, with a warm and encouraging tone."

  - `aiAvatarSettings` (object)
    AI avatar presenter configuration. When set, an AI avatar appears on screen as the video presenter.
Get available avatars from GET /auth/config/ai_avatar_options.

  - `aiAvatarSettings.avatarId` (string)
    Avatar identifier. Use the id value from GET /auth/config/ai_avatar_options.
    Example: "avatar_sarah_001"

  - `aiAvatarSettings.aiVoiceId` (string)
    Override the avatar's default voice with a specific voice ID from GET /auth/config/ai_voice_options.
    Example: "alloy"

  - `videoSourcesPipeline` (array)
    Override the default order in which Shuffll sources media for each scene.
Sources are tried in order; the first one that yields results is used.

Default order: ["stock_footage", "workspace_assets", "generate_from_image", "generate_from_text"]

| Value | Description |
|---|---|
| stock_footage | Search stock video libraries |
| workspace_assets | Use videos from your workspace asset library |
| generate_from_image | Generate a still image (Stability AI) then animate it |
| generate_from_text | Generate a full video clip from scratch using generative AI |
    Enum: "stock_footage", "workspace_assets", "generate_from_image", "generate_from_text"

  - `imagesSourcePipeline` (array)
    Override the default order for sourcing still images used in scene overlays and graphics.

Default order: ["stock_footage", "generate_from_text", "workspace_assets"]

| Value | Description |
|---|---|
| stock_footage | Search stock image libraries |
| generate_from_text | Generate an image using Stability AI |
| workspace_assets | Use images from your workspace asset library |
    Enum: "stock_footage", "generate_from_text", "workspace_assets"

  - `customTemplate` (object)
    Template and scene configuration.

  - `customTemplate.id` (string)
    Template ID from GET /auth/templates. Omit to use the default template.

  - `customTemplate.description` (string)
    Custom description used as the AI system prompt when generating video scripts.
Overrides the template's stored description regardless of toUseTemplateDescription.
Use this to provide brand context, tone guidelines, or audience information that shapes the entire script.
    Example: "Shuffll helps marketing teams create professional videos in minutes. Tone: confident, modern, B2B-focused."

  - `customTemplate.toUseTemplateDescription` (boolean)
    When true, the template's stored description is used as the AI system prompt.
Ignored if description is also provided (explicit description always wins).
    Example: true

  - `customTemplate.flexibilityOverride` (string)
    Controls how strictly the AI follows the template scene structure.
- rigid — Scene order and types are fixed exactly as in the template
- minor — Small adaptations allowed (e.g., skipping an empty scene)
- flexible — AI can freely reorganize or adapt scenes to fit the content
Overrides the flexibility setting stored on the template.
    Enum: "rigid", "minor", "flexible"

  - `customTemplate.assets` (array)
    Media assets (images or videos) to make available for the AI to distribute across scenes.

Each asset in this list is:
1. Validated as a reachable image or video URL
2. Analyzed by AI to generate a description and usage context
3. Downloaded and stored in your workspace under the "Api Assets" folder
4. Made available for the AI to intelligently assign to the most relevant scenes

This is the recommended way to bring your own branded media into a project without pre-assigning clips to specific scenes. For explicit scene-level placement, use scenes[].videosToAdd instead.

  - `customTemplate.assets.url` (string, required)
    Publicly accessible URL of the image or video asset.
    Example: "https://example.com/product-launch.mp4"

  - `customTemplate.assets.type` (string)
    Asset media type. If omitted, Shuffll auto-detects from the URL.
    Enum: "image", "video"

  - `customTemplate.assets.description` (string)
    Optional human-provided description of the asset. If omitted, Shuffll generates one automatically using AI.
Providing a description improves the accuracy of scene matching.
    Example: "A 30-second product demo showing the dashboard onboarding flow."

  - `customTemplate.assets.direction` (string)
    Optional guidance on how the asset should be used (e.g., which scenes it fits, what mood it conveys).
    Example: "Use in the opening scene to establish product credibility."

  - `customTemplate.assets.textHeaderPosition` (number)
    Suggested vertical position for text overlays on this asset (percentage from top).
    Example: 20

  - `customTemplate.videoSourcesByOrder` (array)
    Override the video media fallback pipeline when using a template.
Equivalent to the top-level videoSourcesPipeline field — use one or the other, not both.
If omitted, the pipeline configured on the template is used.
    Enum: "stock_footage", "workspace_assets", "generate_from_image", "generate_from_text"

  - `customTemplate.imageSourcesByOrder` (array)
    Override the image media fallback pipeline when using a template.
Equivalent to the top-level imagesSourcePipeline field — use one or the other, not both.
    Enum: "stock_footage", "generate_from_text", "workspace_assets"

  - `customTemplate.fontsSettings` (object)
    Custom font configuration for the video. Overrides the template's default fonts.
Both primary and secondary must include family and weight if provided.

  - `customTemplate.fontsSettings.primary` (object)
    Primary font used for main headings and titles.

  - `customTemplate.fontsSettings.primary.family` (string)
    Example: "Arimo"

  - `customTemplate.fontsSettings.primary.weight` (string)
    Example: "700"

  - `customTemplate.fontsSettings.secondary` (object)
    Secondary font used for subheadings and body text.

  - `customTemplate.fontsSettings.remaining` (object,null)
    Font applied to all other text elements not covered by primary or secondary.

  - `customTemplate.toUseTemplateFont` (boolean)
    When true, use the font settings stored on the template.
Ignored if fontsSettings is explicitly provided.
    Example: true

  - `customTemplate.preConfigs` (object)
    Global settings applied across all scenes.

  - `customTemplate.preConfigs.bgMusic` (object)
    Background music settings.

  - `customTemplate.preConfigs.bgMusic.volume` (number)
    Music volume relative to voiceover (0–1). 0.3 is a common value for subtle background music.
    Example: 0.3

  - `customTemplate.preConfigs.bgMusic.path` (string)
    Track path from GET /auth/config/music-library (use the relativePath field).
    Example: "/music/upbeat-corporate.mp3"

  - `customTemplate.preConfigs.toCleanAudio` (boolean)
    Automatically remove background noise from audio in user-uploaded videos.
Recommended when your videosToAdd clips contain ambient noise.

  - `customTemplate.preConfigs.aiGenerationStability` (number)
    Creativity vs. accuracy tradeoff for AI image generation (0–1).
Lower = more creative/varied; higher = closer to the prompt.
    Example: 0.5

  - `customTemplate.preConfigs.subtitles` (object)
    Subtitle appearance settings.

  - `customTemplate.preConfigs.subtitles.percentOffset` (number)
    Vertical position from the bottom as a percentage (1–100).

  - `customTemplate.preConfigs.subtitles.textSize` (number)
    Font size in points (8–48).

  - `customTemplate.preConfigs.subtitles.strategy` (string)
    How text is revealed as it is spoken.
- FULL_UTTERANCE — Full sentence appears at once
- WORD_BY_WORD — One word at a time
- KARAOKE — Words highlight progressively
- WORD_HIGHLIGHT — Active word is highlighted
    Enum: "FULL_UTTERANCE", "WORD_BY_WORD", "KARAOKE", "WORD_HIGHLIGHT"

  - `customTemplate.preConfigs.subtitles.fontName` (string)
    Subtitle font name.

  - `customTemplate.preConfigs.subtitles.isBold` (boolean)
    Bold subtitle text.

  - `customTemplate.preConfigs.subtitles.primaryColour` (string)
    Primary text color (hex).
    Example: "#FFFFFF"

  - `customTemplate.preConfigs.subtitles.secondaryColour` (string)
    Shadow/secondary text color (hex).
    Example: "#000000"

  - `customTemplate.preConfigs.subtitles.outlineColour` (string)
    Text outline color (hex).
    Example: "#000000"

  - `customTemplate.preConfigs.subtitles.styles` (object)
    Fine-grained style overrides for normal and highlighted subtitle states.
Used with KARAOKE and WORD_HIGHLIGHT strategies to style the active word differently.

  - `customTemplate.preConfigs.subtitles.styles.normal` (object)
    Style for words that are not currently being spoken.

  - `customTemplate.preConfigs.subtitles.styles.normal.color` (string)
    Text color (hex).
    Example: "#FFFFFF"

  - `customTemplate.preConfigs.subtitles.styles.normal.fontSize` (number)
    Font size override for normal words.

  - `customTemplate.preConfigs.subtitles.styles.highlight` (object)
    Style for the word currently being spoken.

  - `customTemplate.preConfigs.subtitles.styles.highlight.color` (string)
    Highlight text color (hex).
    Example: "#FFD700"

  - `customTemplate.preConfigs.subtitles.styles.highlight.fontSize` (number)
    Font size override for the highlighted word.

  - `customTemplate.scenes` (array)
    Per-scene overrides. Only include scenes you want to customize.
Scenes not listed here are auto-generated using the template and your workspace branding.

  - `customTemplate.scenes.id` (string)
    Scene ID from the template. Get scene IDs from GET /auth/templates/{templateId}.

  - `customTemplate.scenes.staticScript` (string)
    Force a fixed voiceover script for this scene, bypassing AI generation.
To render the scene with no voiceover at all, provide a single space " ".

  - `customTemplate.scenes.moreDetailsAboutScene` (string)
    Extra guidance for the AI when writing this scene's script.
Example: "Open with a bold statistic about player retention."

  - `customTemplate.scenes.toGenerateMissingImages` (boolean)
    When true, any image slots in this scene's template layout that are not provided in dynamicValues will be auto-generated using Stability AI.
When false (default), unfilled image slots are left empty.
    Example: true

  - `customTemplate.scenes.toUseSubtitles` (boolean)
    Enable or disable subtitles for this scene. Overrides the global subtitle setting.

  - `customTemplate.scenes.toMakeVOAsMasterInDefault` (boolean)
    Make the AI voiceover the master audio track, taking priority over any video audio.

  - `customTemplate.scenes.wordBoost` (array)
    Words to boost in speech recognition transcription for this scene.
Use this for product names, brand names, or uncommon terms that the transcription model might mis-hear.
    Example: ["Shuffll","MPEG-DASH","Riot Games"]

  - `customTemplate.scenes.customSpelling` (array)
    Custom spelling corrections for the subtitle transcript of this scene.
Each entry maps a list of heard variations (from) to the correct spelling (to).
Useful when the AI voiceover or transcription produces a slightly wrong spelling of a proper noun.

  - `customTemplate.scenes.customSpelling.from` (array, required)
    Incorrect or alternative spellings to replace.
    Example: ["Shuffel","Shufflle"]

  - `customTemplate.scenes.customSpelling.to` (string, required)
    The correct spelling.
    Example: "Shuffll"

  - `customTemplate.scenes.staticText` (array)
    Fixed text values to display in this scene's text elements, used when toUseStaticText is true.
Provided in order — each string maps to a text element in the scene layout.
    Example: ["Your headline here","Supporting detail line"]

  - `customTemplate.scenes.toUseStaticText` (boolean)
    When true, use the strings in staticText as the scene's on-screen text instead of AI-generated content.

  - `customTemplate.scenes.punctuationsToRemove` (array)
    Punctuation marks to strip from the subtitle text for this scene.
    Example: [",",".","!"]

  - `customTemplate.scenes.dynamicValues` (array)
    Override specific visual elements in the scene (text, colors, images, logos).
Get the available element types and positions from GET /auth/templates/{templateId}.

Common type values: header, topic, cta, website, logo, image, color_fill, company, tagline.
    Example: [{"position":0,"type":"header","value":"Innovating Player Experience"},{"position":0,"type":"logo","value":"https://example.com/logo.png"},{"position":0,"type":"website","value":"https://riotgames.com"}]

  - `customTemplate.scenes.dynamicValues.position` (number)
    Element position index (from the template definition).

  - `customTemplate.scenes.dynamicValues.type` (string)
    Element type (e.g., header, logo, image, color_fill).

  - `customTemplate.scenes.dynamicValues.value` (string)
    The value to set for this element.

  - `customTemplate.scenes.videosToAdd` (array)
    Videos to place in this scene. These bypass the media fallback pipeline entirely — provided videos are always used first.

Use uploadPath from GET /auth/workspace/{workspaceId}/assets to reference a workspace asset, or provide any publicly accessible URL.

Use stagePositionNumber to target a specific layout slot within the scene. Available positions come from availableStagePositions in GET /auth/templates/{templateId}.

  - `customTemplate.scenes.videosToAdd.url` (string)
    Public video URL. Use uploadPath from GET /auth/workspace/{workspaceId}/assets to reference a workspace asset.
    Example: "https://content.shuffll.com/workspace/product-demo.mp4"

  - `customTemplate.scenes.videosToAdd.stagePositionNumber` (number,null)
    Layout slot to place this video in. Corresponds to the position value from availableStagePositions in the template.
Pass null to use the default (highest available) position.
    Example: 100

  - `customTemplate.scenes.videosToAdd.isMaster` (boolean)
    Marks this as the primary video layer for the scene.
The master video drives timing and is synced with voiceover and subtitles.
Only one video per scene can be master. If none is marked, the longest video is chosen automatically.

  - `customTemplate.scenes.videosToAdd.isMuted` (boolean)
    Mute this video's audio (voiceover will still play over it).

  - `customTemplate.scenes.videosToAdd.toFlip` (boolean)
    Mirror the video horizontally.

  - `customTemplate.scenes.videosToAdd.toAutoTrim` (boolean,null)
    Automatically trim the video to match the scene duration.

  - `customTemplate.scenes.videosToAdd.toUseSubtitles` (boolean)
    Use this video's own subtitles/audio instead of the AI voiceover for this scene.

  - `customTemplate.scenes.videosToAdd.toGenerateSubtitles` (boolean)
    Generate subtitles by transcribing this video's audio track.
Different from toUseSubtitles — this transcribes the video's own speech rather than using the AI voiceover.

  - `customTemplate.toReturnAnErrorIfMissingScene` (boolean)
    When true, returns a 400 error if a scene ID in scenes[] does not exist in the template.
When false (default), unrecognized scenes are silently skipped.

## Response 200 fields (application/json):

  - `projectId` (string)
    Unique identifier for the created project
    Example: "6947b539cc95ea68854bb523"

## Response 400 fields (application/problem+json):

  - `type` (string)
    Example: "object"

  - `title` (string)
    Example: "Validation failed"

  - `message` (string)
    Example: "Bad Request"

## Response 401 fields (application/problem+json):

  - `type` (string)
    Example: "object"

  - `title` (string)
    Example: "Validation failed"

  - `message` (string)
    Example: "Bad Request"