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, sent as a Bearer token in the Authorization header.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  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 -H "Authorization: Bearer YOUR_API_KEY" \
  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.region = "eu-west-1";

const projects = await client.listProjects();

import impossiblefx as fx

client = fx.Client(
    api_key="YOUR_API_KEY",
    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 -H "Authorization: Bearer YOUR_API_KEY" \
  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 -H "Authorization: Bearer YOUR_API_KEY" \
  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 -H "Authorization: Bearer YOUR_API_KEY" \
  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 -H "Authorization: Bearer YOUR_API_KEY" \
  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 -H "Authorization: Bearer YOUR_API_KEY" \
  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 -H "Authorization: Bearer YOUR_API_KEY" \
  --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 -H "Authorization: Bearer YOUR_API_KEY" \
  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 -H "Authorization: Bearer YOUR_API_KEY" \
  "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 -H "Authorization: Bearer YOUR_API_KEY" \
  --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 -H "Authorization: Bearer YOUR_API_KEY" \
  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 -H "Authorization: Bearer YOUR_API_KEY" \
  -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