Get project

Shuffll API (1.2.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

The Shuffll API enables seamless automation and integration of Shuffll's AI-powered video creation platform into external workflows.

What is Shuffll?

Shuffll is an AI-powered platform designed to automate and streamline video content creation for businesses, marketers, and content creators. By leveraging machine learning, Shuffll enables users to generate high-quality videos efficiently, reducing production time and effort while maintaining creative control.

With Shuffll's API, developers can integrate automated video generation into their applications, enabling seamless video content production at scale. Whether it's for marketing, social media, training, or corporate communications, Shuffll simplifies the process of creating engaging and professional videos.

Key Features

AI-Driven Video Creation – Generate videos automatically based on structured input, scripts, or templates.
Smart Editing & Automation – Apply transitions, overlays, and effects without manual editing.
Custom API Endpoints – Programmatically generate, edit, and manage video content.
Brand Consistency – Ensure that videos align with predefined brand styles and messaging.
Seamless Integrations – Connect with third-party tools, media libraries, and content management systems.

Shuffll's API empowers developers to automate video production, integrate AI-enhanced video workflows, and create personalized video content at scale—all with minimal effort.

Download OpenAPI description

index.json

index.yaml

Overview

URL

https://shuffll.com

E-mail

info@shuffll.com

License

MIT

Servers

Mock server

https://api-docs.shuffll.com/_mock/apis

https://api.shuffll.com/api/v1

Configuration

Retrieve available options for AI voices, avatars, background music, and video category tags. Call these endpoints to populate field values when creating a project.

Operations

Organizations

Manage organizations and retrieve their workspaces, branding, and settings.

Operations

Workspaces

Manage workspaces within an organization, and list projects within a workspace.

Operations

Branding

Read and update branding configuration (logo, colors, company info, pronunciations) for a workspace or organization.

Operations

Assets

Upload, organize, rename, move, and delete media assets in a workspace. Assets can be referenced directly in project creation requests.

Operations

Templates

Browse and retrieve reusable video templates. Templates define the scene structure and visual style of a project.

Operations

Projects

Create, monitor, and manage AI-generated video projects.

Operations

Create project

Request

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.

Your videos (customTemplate.scenes[].videosToAdd) — Videos you explicitly provide are always used first.
Stock footage — Shuffll searches stock video libraries for footage matching the scene content.
Workspace assets — Shuffll looks in your workspace asset library for relevant clips.
Image → Video animation — A still image is generated (via Stability AI) and animated into a short clip.
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:

"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:

{
  "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.

Security

ShuffllApiKey

Bodyapplication/json

promptstringrequired

The content/topic for your video

Example: "Explore Riot Games' Innovative Player Experiences"

promptTypestring

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"

Example: "Prompt"

languagestring

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"

Example: "en"

videoLengthnumber

Target video duration in minutes. 0.5 → ~30 sec · 1 → ~1 min · 2 → ~2 min · 3 → ~3 min

Enum0.5123

Example: 2

storyTellingTechniquestring

Storytelling structure for the script. Use the technique value from GET /auth/config/storytelling_techniques.

Example: "The Before-and-After Transformation"

toneOfVoicestring

Narration tone. Use the id value from GET /auth/config/tone_of_voice.

Enum"Natural""Professional""Informative""Inspirational""Energetic"

Example: "Professional"

videoTagIdstring

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"

webhookstring(uri)

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"

additionalParamsobject

Arbitrary data to embed in the webhook payload (e.g., campaign ID, user ID).

Example: {"campaignId":"camp_123","userId":"usr_456"}

toAutoEnhanceboolean

Automatically start enhancement after project creation completes. Defaults to true for integration API requests.

Example: true

toAutoExportboolean

Automatically start export after enhancement completes. Combine with webhook to receive the result with no polling required.

Example: false

aiVoiceSettingsobject

AI voiceover configuration. Get available voices from GET /auth/config/ai_voice_options.

aiAvatarSettingsobject

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.

videoSourcesPipelineArray of strings

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

Items Enum"stock_footage""workspace_assets""generate_from_image""generate_from_text"

Example: ["workspace_assets","stock_footage"]

imagesSourcePipelineArray of strings

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

Items Enum"stock_footage""generate_from_text""workspace_assets"

Example: ["workspace_assets","generate_from_text"]

customTemplateobject

Template and scene configuration.

curl -i -X POST \
  https://api-docs.shuffll.com/_mock/apis/auth/project/create \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "prompt": "Breaking the Agency Mold - Building Long-Term Partnerships with Data",
    "promptType": "Prompt",
    "language": "en",
    "videoLength": 2,
    "toneOfVoice": "Professional",
    "videoTagId": "Marketing",
    "storyTellingTechnique": "The Before-and-After Transformation",
    "toAutoEnhance": true,
    "toAutoExport": true,
    "webhook": "https://your-app.com/hooks/shuffll-export",
    "additionalParams": {
      "campaignId": "camp_123"
    },
    "aiVoiceSettings": {
      "voiceId": "alloy",
      "voiceType": "open-ai",
      "voiceSpeed": 1
    },
    "customTemplate": {
      "id": "67682e831de738f85b0d0fc9",
      "description": "Agency-focused video brand. Tone: confident, data-driven, B2B. Audience: marketing directors.",
      "flexibilityOverride": "flexible",
      "toUseTemplateFont": true,
      "assets": [
        {
          "url": "https://example.com/product-demo.mp4",
          "type": "video",
          "description": "60-second product walkthrough showing the analytics dashboard.",
          "direction": "Use in a middle scene to demonstrate product value."
        },
        {
          "url": "https://example.com/team-photo.jpg",
          "type": "image",
          "description": "Company team photo, outdoor setting."
        }
      ],
      "videoSourcesByOrder": [
        "workspace_assets",
        "stock_footage",
        "generate_from_image"
      ],
      "preConfigs": {
        "bgMusic": {
          "volume": 0.35,
          "path": "/music/upbeat-corporate.mp3"
        },
        "toCleanAudio": false,
        "subtitles": {
          "strategy": "WORD_HIGHLIGHT",
          "textSize": 18,
          "percentOffset": 40,
          "fontName": "Arimo",
          "isBold": true,
          "primaryColour": "#FFFFFF",
          "outlineColour": "#000000",
          "styles": {
            "normal": {
              "color": "#FFFFFF"
            },
            "highlight": {
              "color": "#FFD700"
            }
          }
        }
      },
      "scenes": [
        {
          "id": "a517722a-582b-4f8c-bb8f-c8e8014cf6cc",
          "staticScript": "Data-driven agencies don'\''t just win clients — they keep them for years.",
          "dynamicValues": [
            {
              "position": 0,
              "type": "header",
              "value": "Breaking the Agency Mold"
            },
            {
              "position": 0,
              "type": "logo",
              "value": "https://example.com/logo.png"
            }
          ],
          "wordBoost": [
            "Shuffll",
            "ROI"
          ],
          "customSpelling": [
            {
              "from": [
                "Shuffel",
                "Shufflle"
              ],
              "to": "Shuffll"
            }
          ]
        },
        {
          "id": "08865dcb-d8f3-4dfd-964d-76304fbbfa9d",
          "moreDetailsAboutScene": "Focus on the before/after contrast — struggling agency vs. data-driven success.",
          "toGenerateMissingImages": true,
          "videosToAdd": [
            {
              "url": "https://content.shuffll.com/workspace/agency-intro.mp4",
              "isMaster": true,
              "stagePositionNumber": 100,
              "isMuted": false,
              "toAutoTrim": true
            }
          ]
        }
      ]
    }
  }'

Responses

Project created successfully. Returns the project ID.

Bodyapplication/json

projectIdstring

Unique identifier for the created project

Example: "6947b539cc95ea68854bb523"

Response

application/json

{
  "projectId": "6947b539cc95ea68854bb523"
}

Get project creation status

Request

Poll this endpoint after creating a project to track AI generation progress.

Returns a status field with one of three values:

`status`	Meaning
`STRUCTURE`	The AI is building the storyline and script
`GENERATING_IMAGES`	Scene visuals and media are being generated
`DONE`	Project creation is complete — enhancement will begin automatically

Keep polling until status is DONE. After that, use GET /auth/project/{projectId}/edit/status/enhance to track enhancement progress.

Security

ShuffllApiKey

Path

projectIdstring(uuid)required

Unique identifier for the project

Example: dad4bce8-f5cb-4078-a211-995864315e39

curl -i -X GET \
  https://api-docs.shuffll.com/_mock/apis/auth/project/dad4bce8-f5cb-4078-a211-995864315e39/create/status \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Status retrieved successfully.

Bodyapplication/json

statusstring

Current creation stage of the project

Enum"STRUCTURE""GENERATING_IMAGES""DONE"

Example: "DONE"

Response

application/json

{
  "status": "DONE"
}

Get project

Request

Retrieve the full details of a specific project, including its current status, name, and workspace.

Use the status field to determine if the project is still being generated:

STRUCTURE — initial structure is being built
GENERATING_IMAGES — images and media are being generated
EDITING — enhancement is running automatically
DONE — project is ready

Security

ShuffllApiKey

Path

projectIdstring(uuid)required

Unique identifier for the project

Example: dad4bce8-f5cb-4078-a211-995864315e39

curl -i -X GET \
  https://api-docs.shuffll.com/_mock/apis/auth/project/dad4bce8-f5cb-4078-a211-995864315e39 \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successfully retrieved project details.

Bodyapplication/json

idstring

Unique project identifier

Example: "6947b539cc95ea68854bb523"

namestring

Project name

Example: "Breaking the Agency Mold"

statusstring

Current project status

Enum"STRUCTURE""GENERATING_IMAGES""EDITING""DONE"

Example: "DONE"

createdAtstring(date-time)

Project creation timestamp

Example: "2025-12-15T07:26:34.333Z"

workspaceIdstring

ID of the workspace this project belongs to

Example: "693fb82afd8d1c43077ba0fe"

Response

application/json

{
  "id": "6947b539cc95ea68854bb523",
  "name": "Breaking the Agency Mold",
  "status": "DONE",
  "createdAt": "2025-12-15T07:26:34.333Z",
  "workspaceId": "693fb82afd8d1c43077ba0fe"
}

Delete project

Request

Permanently delete a project and all associated data.

This action cannot be undone.

Security

ShuffllApiKey

Path

projectIdstring(uuid)required

Unique identifier for the project

Example: dad4bce8-f5cb-4078-a211-995864315e39

curl -i -X DELETE \
  https://api-docs.shuffll.com/_mock/apis/auth/project/dad4bce8-f5cb-4078-a211-995864315e39 \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Project deleted successfully.

Response

No content

Enhance

Monitor the automatic post-production enhancement process (branding, subtitles, audio cleanup) that runs after a project is created.

Operations

Export

Trigger video export and retrieve the final downloadable video URLs.

Operations

Shuffll API (1.2.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Configuration

Organizations

Workspaces

Branding

Assets

Templates

Projects

Create project

Request

Prompt Types

Scene Media — Fallback System

Missing Images (`toGenerateMissingImages`)

AI Presenter (Avatar)

Webhooks

After creating a project

Responses

Was this helpful?

Get project creation status

Request

Responses

Was this helpful?

Get project

Request

Responses

Was this helpful?

Delete project

Request

Responses

Was this helpful?

Enhance

Export

Shuffll API (1.2.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Configuration

Organizations

Workspaces

Branding

Assets

Templates

Projects

Create project

RequestExpand all

Prompt Types

Scene Media — Fallback System

Missing Images (toGenerateMissingImages)

AI Presenter (Avatar)

Webhooks

After creating a project

Responses

Was this helpful?

Get project creation status

Request

Responses

Was this helpful?

Get project

Request

Responses

Was this helpful?

Delete project

Request

Responses

Was this helpful?

Enhance

Export

Shuffll API (1.2.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Request

Missing Images (`toGenerateMissingImages`)