Project API

The Project API lets you manage projects, upload assets (videos, images, fonts, sounds), and work with dynamic movie templates. Unlike the Render API, which handles video rendering and retrieval, the Project API covers everything else — creating projects, managing their contents, and publishing them to render clusters.

Base URL

All Project API requests go to a regional endpoint:

https://api-{region}.impossible.io

Replace {region} with your project’s region:

Authentication

Every Project API request requires your API Key and API Secret, sent as HTTP Basic authentication credentials. The API Key is the username and the API Secret is the password.

curl -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/v1/list/project

Or as an Authorization header with a Base64-encoded key:secret string:

curl -H "Authorization: Basic BASE64_ENCODED_KEY_SECRET" \
  https://api-eu-west-1.impossible.io/v1/list/project

Projects

Projects are the top-level containers for your video templates. Each project holds assets (media files, fonts), movie compositions, and configuration.

List all projects

Returns a list of all projects in your account.

Endpoint: GET /v1/list/project

curl -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/v1/list/project

import { ImpossibleFX } from "impossiblefx";

const client = new ImpossibleFX();
client.config.apikey = "YOUR_API_KEY";
client.config.apisecret = "YOUR_API_SECRET";
client.config.region = "eu-west-1";

const projects = await client.listProjects();

import impossiblefx as fx

client = fx.Client(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    region="eu-west-1"
)

projects = client.list_projects()

Create a project

Creates a new empty project with the given name.

Endpoint: POST /v1/project/{name}

curl -X POST -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/v1/project/my-new-project

The response includes the project UID, which you’ll use in all subsequent API calls for this project.

Delete a project

Permanently deletes a project and all of its assets.

Endpoint: DELETE /v1/project/{project-uid}

curl -X DELETE -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/v1/project/abc123-def456

Publish a project to additional regions

Publishes a project to a render cluster in another region. This is only needed if you want your project available for rendering in multiple regions — for example, to serve users in both Europe and Asia with low latency.

Most projects don’t need this. By default, your project is available in the region where it was created, and render requests sent to the global endpoint are routed to the nearest region that has the project. Publishing to additional clusters lets you geo-distribute a project so that requests from any region are served locally.

Endpoint: POST /v1/publish/{project-uid}/{cluster-name}

# Publish a project (created in eu-west-1) to the Singapore region
curl -X POST -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/v1/publish/abc123-def456/ap-southeast-1

Assets

Assets are the media files inside a project — videos, images, fonts, and audio files used by your movie templates. The assets API lets you list, upload, retrieve, and delete these files.

List assets

Returns a list of all assets in a project.

Endpoint: GET /v1/list/data/{project-uid}

curl -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/v1/list/data/abc123-def456

Retrieve an asset

Downloads a specific asset file from a project.

Endpoint: GET /v1/data/{project-uid}/{filename}

curl -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/v1/data/abc123-def456/background.mp4 \
  --output background.mp4

Upload or update an asset

Uploads a new asset or replaces an existing one. The file contents go in the request body.

Endpoint: PUT /v1/data/{project-uid}/{filename}

curl -X PUT -u YOUR_API_KEY:YOUR_API_SECRET \
  --data-binary @logo.png \
  https://api-eu-west-1.impossible.io/v1/data/abc123-def456/logo.png

Delete an asset

Removes an asset from a project.

Endpoint: DELETE /v1/data/{project-uid}/{filename}

curl -X DELETE -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/v1/data/abc123-def456/logo.png

Multipart upload

For large video files, use multipart upload to break the file into smaller chunks. This is more reliable than a single PUT request for large files, since individual chunks can be retried on failure.

The process has three steps: initiate the upload, send each chunk, then signal completion.

Step 1 — Initiate the upload

Endpoint: POST /chunked/videos/{project-uid}

curl -X POST -u YOUR_API_KEY:YOUR_API_SECRET \
  "https://api-eu-west-1.impossible.io/chunked/videos/abc123-def456?chunk_count=5&chunk_size=10485760&name=hero-video.mp4"

The response includes an upload-id you’ll use for the remaining steps.

Step 2 — Upload each chunk

Send each chunk as a separate request. Chunks must all be the same size except the last one.

Endpoint: POST /chunked/videos/{project-uid}/{upload-id}/chunks

curl -X POST -u YOUR_API_KEY:YOUR_API_SECRET \
  --data-binary @chunk_0.bin \
  "https://api-eu-west-1.impossible.io/chunked/videos/abc123-def456/upload-789/chunks?chunk_id=0"

Step 3 — Complete the upload

After all chunks are uploaded, signal that the upload is complete.

Endpoint: POST /chunked/videos/{project-uid}/{upload-id}/finished

curl -X POST -u YOUR_API_KEY:YOUR_API_SECRET \
  https://api-eu-west-1.impossible.io/chunked/videos/abc123-def456/upload-789/finished

The system assembles the chunks into the final asset file once this request completes.

Dynamic movies (SDLs)

Dynamic movies are templates defined using SDL (Scene Description Language) that can be created and managed programmatically via the API. For a guide on writing SDL, see SDL Scripting.

The SDL endpoints follow the same pattern as assets:

# Upload an SDL template
curl -X PUT -u YOUR_API_KEY:YOUR_API_SECRET \
  -H "Content-Type: application/json" \
  --data-binary @welcome-video.json \
  https://api-eu-west-1.impossible.io/v1/sdl/abc123-def456/welcome-video

Error responses