# Shuffll API

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.


Version: 1.2.0
License: MIT

## Servers

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

## Security

### ShuffllApiKey

API key for authentication. Obtain from Account Settings > API Integration.
Format: sfl-{key}.{secret}:{token}


Type: apiKey
In: header
Name: x-api-key

## Download OpenAPI description

[Shuffll API](https://api-docs.shuffll.com/_bundle/apis/index.yaml)

## 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.

### Get storytelling techniques

 - [GET /auth/config/storytelling_techniques](https://api-docs.shuffll.com/apis/configuration/getstorytellingtechniques.md): Retrieve all available storytelling techniques for video creation.
Returns an array of 12 storytelling techniques with descriptions, explanations of why they work, and examples.

Use these techniques when creating projects to structure your video narrative effectively.

### Get tone of voice options

 - [GET /auth/config/tone_of_voice](https://api-docs.shuffll.com/apis/configuration/gettoneofvoice.md): Retrieve all available tone of voice options for video narration.
Returns an array of tone options with descriptions.

Use the id value as toneOfVoice when creating a project.

### Get video category tags

 - [GET /auth/config/video_tags](https://api-docs.shuffll.com/apis/configuration/getvideotags.md): Retrieve all available video category tags.

Use the id value as videoTagId when creating a project to categorize your video (e.g., Marketing, Explainer, Training).

### Get AI voice options

 - [GET /auth/config/ai_voice_options](https://api-docs.shuffll.com/apis/configuration/getaivoiceoptions.md): Retrieve all available AI voice-over options and tone styles.

Returns two arrays:
- aiVoiceOptions — the list of available voices. Use the id value as aiVoiceSettings.voiceId when creating a project.
- aiVoiceTones — tone styles that can be layered on top of a voice (e.g., friendly, professional, dramatic).

Voices are provided by either OpenAI or ElevenLabs depending on the voiceType field.

### Get AI avatar options

 - [GET /auth/config/ai_avatar_options](https://api-docs.shuffll.com/apis/configuration/getaiavataroptions.md): Retrieve all available AI avatar presenter options.

Each avatar has a name, accent, and a preview video URL. Use the id value when configuring an AI avatar presenter for your project.

### Get background music library

 - [GET /auth/config/music-library](https://api-docs.shuffll.com/apis/configuration/getmusiclibrary.md): Retrieve all available background music tracks.

Use the relativePath value as customTemplate.preConfigs.bgMusic.path when creating a project to set the background music.

## Organizations

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

### Get organization list

 - [GET /auth/organization/list](https://api-docs.shuffll.com/apis/organizations/getorganizationlist.md): Retrieve array of all organizations the user has access to.

Returns metadata for each organization including:
- Organization ID and name
- Workspaces within each organization
- Branding configuration (colors, logos, company info)
- Video prompts and ideas
- User access status and user count

### Get specific organization

 - [GET /auth/organization/{organizationId}](https://api-docs.shuffll.com/apis/organizations/getorganizationbyid.md): Retrieve detailed information about a specific organization including:
- Organization ID and name
- All workspaces with detailed metrics (asset count, project count, template count)
- Complete branding configuration
- User information

## Workspaces

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

### Get workspace

 - [GET /auth/organization/{organizationId}/workspace/{workspaceId}](https://api-docs.shuffll.com/apis/workspaces/getworkspacebyid.md): Retrieve detailed information about a specific workspace including:
- Workspace ID and name
- Metrics (asset count, project count, template count, user count)
- Complete branding configuration
- Video prompts and ideas
- Creator information

### Update workspace

 - [PUT /auth/organization/{organizationId}/workspace/{workspaceId}](https://api-docs.shuffll.com/apis/workspaces/updateworkspace.md): Update fields on a specific workspace.

Currently supports updating the workspace name.
To update workspace branding (logo, colors, company info), use PUT /auth/branding/entity.

### List workspace projects

 - [GET /auth/workspace/{workspaceId}/projects](https://api-docs.shuffll.com/apis/workspaces/listworkspaceprojects.md): Retrieve all projects in a specific workspace.

Returns a list of project summaries including each project's ID, name, current status, and creation date.
Use this endpoint to enumerate existing projects before exporting or checking their status.

## Branding

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

### Get branding

 - [GET /auth/branding/entity](https://api-docs.shuffll.com/apis/branding/getbranding.md): Retrieve the branding configuration for a workspace or organization.

Pass either workspaceId or organizationId as a query parameter to specify which entity's branding to retrieve.

### Update branding property

 - [PUT /auth/branding/entity](https://api-docs.shuffll.com/apis/branding/updatebranding.md): Update a single branding property for a workspace or organization.

This endpoint uses a property-name/value pattern — each call updates one property at a time.

Supported propertyName values:

| propertyName | Type | Description |
|---|---|---|
| logo | string (URL) | Primary logo URL |
| logoW | string (URL) | White/light logo URL |
| colors | object | Brand color palette |
| company | object | Company metadata (name, domain, etc.) |
| about | string | About text used in AI video scripts |
| pronunciations | array | Custom pronunciation rules for AI voiceover |
| enabled | boolean | Enable or disable branding |

For colors, pass an object with colorPrimary, colorSecondary, and colorExtra hex values.

See the examples below for common update patterns.

## Assets

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

### List assets

 - [GET /auth/workspace/{workspaceId}/assets](https://api-docs.shuffll.com/apis/assets/listassets.md): Retrieve all assets in a workspace.

Use the type query parameter to filter by asset type (e.g., image, video, audio).
Use the folder query parameter to list assets within a specific folder path.

The uploadPath field on each asset is the CDN URL you can use directly in videosToAdd[].url when creating a project.

### Upload asset

 - [POST /auth/workspace/{workspaceId}/assets](https://api-docs.shuffll.com/apis/assets/uploadasset.md): Upload one or more files to a workspace as assets.

Files are uploaded as multipart/form-data. Each uploaded file becomes an asset in the workspace.

For video files, a DASH streaming version is automatically generated.

The returned uploadPath on each asset is the CDN URL that can be used directly in videosToAdd[].url when creating a project.

### Delete assets

 - [DELETE /auth/workspace/{workspaceId}/assets](https://api-docs.shuffll.com/apis/assets/deleteassets.md): Delete one or more assets from a workspace by their IDs.

This action is permanent and cannot be undone.

### Create folder

 - [POST /auth/workspace/{workspaceId}/assets/folder](https://api-docs.shuffll.com/apis/assets/createassetfolder.md): Create a new folder in the workspace asset library.

Folders are used to organize assets. The folder name must be unique within the workspace.

### Move assets

 - [PUT /auth/workspace/{workspaceId}/assets/move](https://api-docs.shuffll.com/apis/assets/moveassets.md): Move one or more assets to a different folder.

The target folder must exist. Use POST /auth/workspace/{workspaceId}/assets/folder to create a folder first if needed.

### Rename asset

 - [PUT /auth/workspace/{workspaceId}/assets/{assetId}/file](https://api-docs.shuffll.com/apis/assets/renameasset.md): Rename an existing asset by updating its display name.

## Templates

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

### Get all templates

 - [GET /auth/templates](https://api-docs.shuffll.com/apis/templates/getalltemplates.md): Retrieve a list of all templates you have created in your account.

Templates are reusable video project structures that define scene order, types, and configurations.

### Get templates by organization and workspace

 - [GET /auth/organization/{organizationId}/workspace/{workspaceId}/templates](https://api-docs.shuffll.com/apis/templates/gettemplatesbyorgworkspace.md): Retrieve all templates for a specific organization and workspace.

This endpoint allows you to get templates from a particular organization and workspace rather than the default ones.

### Get specific template

 - [GET /auth/templates/{templateId}](https://api-docs.shuffll.com/apis/templates/gettemplatebyid.md): Retrieve detailed information about a specific template including:
- Template ID, name, and description
- All scenes with their types and order
- Dynamic fields for each scene (headers, colors, texts, voice settings, etc.)
- Scene configuration options

Use this endpoint to understand the template structure before creating a project from it.

## Projects

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

### Create project

 - [POST /auth/project/create](https://api-docs.shuffll.com/apis/projects/createproject.md): 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.

### Get project creation status

 - [GET /auth/project/{projectId}/create/status](https://api-docs.shuffll.com/apis/projects/getprojectcreatestatus.md): 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.

### Get project

 - [GET /auth/project/{projectId}](https://api-docs.shuffll.com/apis/projects/getprojectbyid.md): 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

### Delete project

 - [DELETE /auth/project/{projectId}](https://api-docs.shuffll.com/apis/projects/deleteproject.md): Permanently delete a project and all associated data.

This action cannot be undone.

## Enhance

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

### Get project enhancement status

 - [GET /auth/project/{projectId}/edit/status/enhance](https://api-docs.shuffll.com/apis/enhance/getenhancestatus.md): Check the progress of the automatic enhancement process for a project.

Enhancement starts automatically after a project is created. Poll this endpoint to track progress.

- A 202 response means enhancement is still in progress — continue polling.
- A 200 response with isDone: true means enhancement is complete and the project is ready to export.

## Export

Trigger video export and retrieve the final downloadable video URLs.

### Export project

 - [POST /auth/project/{projectId}/edit/export](https://api-docs.shuffll.com/apis/export/exportproject.md): Trigger the export of a completed project to a video file.

Returns a projectId and editId that can be used to poll the export status.

Prerequisites: The project must have completed enhancement before exporting.
Check enhancement status with GET /auth/project/{projectId}/edit/status/enhance.

### Get project export status

 - [GET /auth/project/{projectId}/edit/status/export](https://api-docs.shuffll.com/apis/export/getexportstatus.md): Check the progress of a project export job.

- A 202 response means the export is still being processed — continue polling.
- A 200 response with isDone: true means the export is complete. The urls object will contain the video file URLs.

URLs returned on completion:
- uploadPath — direct MP4 download URL
- dashPath — MPEG-DASH streaming manifest URL