Import Media

Import media files into a new or existing project and create compositions.

This endpoint can:

• Create a new project if project_id is not provided
• Import media files from URLs
• Create multitrack sequences
• Create compositions (timelines) from existing or new media in the project
• Trigger transcription and other background processing tasks

Media URL requirements

• URLs must be accessible by Descript servers
• URLs must support HTTP Range requests
• Recommended to sign URLs for 12-48 hours to reduce chance of failure
• Supported file types

Async Operations

Imports run in the background and return a job_id. Monitor progress via the GET /jobs/ endpoint.

Dynamic webhook

If callback_url is provided, Descript will POST the job status to that URL when the job finishes (successfully or not).

The payload will match the format returned by GET /jobs/.

POST /jobs/import/project_media

cURL

create_with_composition

curl --request POST \
  --url https://descriptapi.com/v1/jobs/import/project_media \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_name": "Marketing Video",
  "add_media": {
    "Misc/intro.mp4": {
      "url": "https://example.com/intro.mp4"
    },
    "demo.mp4": {
      "url": "https://example.com/demo.mp4"
    },
    "Misc/outro.mp4": {
      "url": "https://example.com/outro.mp4"
    }
  },
  "add_compositions": [
    {
      "name": "Rough Cut",
      "clips": [
        {
          "media": "Misc/intro.mp4"
        },
        {
          "media": "demo.mp4"
        },
        {
          "media": "Misc/outro.mp4"
        }
      ]
    }
  ]
}
'

201

Example

{
  "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776",
  "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2",
  "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb",
  "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"
}

Authorizations

Authorization · string · header · required

Personal API token created in Descript Settings → API Tokens. See the Authentication section for details.

Body

application/json

Media import and project creation request

Request to import media into a project and optionally create compositions. This operation will:

• Create a new project if project_id is not provided (using the drive associated with the personal token)
• Import media files from URLs or create multitrack sequences
• Optionally create one or more compositions
• Trigger transcription and other background processing

project_id · string<uuid>

[Work in progress] Importing into an existing project is not yet supported. Currently, a new project is always created.

Existing project ID to import media into. If not provided, a new project will be created. When importing into an existing project, media filenames must not conflict with existing files.

Example:

"9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"

project_name · string

Name for the new project. Only used when project_id is not provided.

Example:

"Marketing Video"

team_access · enum<string> · default: none

Access level for drive members. Only applicable when creating a new project (when project_id is not provided). Defaults to none if not specified.

• edit: Users can edit the project
• comment: Users can view and comment but not edit
• view: Users can view but not comment or edit
• none: No shared access (private to owner)

Available options: edit, comment, view, none

Example:

"edit"

add_media · object

Map of media reference IDs (display names with optional folder paths) to media import items. Keys are the display names that will appear in the project (e.g., "Misc/intro.mp4" or "demo.mp4"). Values define how to import each media item (URL import or multitrack sequence).

Show child attributes

Example:

{
  "Misc/intro.mp4": { "url": "https://example.com/intro.mp4" },
  "demo.mp4": { "url": "https://example.com/demo.mp4" },
  "Multicam_Track": {
    "tracks": [
      {
        "media": "Recordings/camera1.mp4",
        "offset": 0
      },
      {
        "media": "Recordings/camera2.mp4",
        "offset": 50
      }
    ]
  }
}

add_compositions · object[]

Optional list of compositions to create in the project

Show child attributes

callback_url · string<uri>

Optional webhook URL to call when the job completes or fails. Descript will POST the job status (same format as GET /jobs/{job_id}) to this URL.

Example:

"https://example.com/webhooks/descript/job_callback"

Response

201

application/json

Import job created successfully

Response returned when creating an import job

job_id · string<uuid> · required

Unique identifier for the job

Example:

"6dc3f30a-58c2-4174-96a6-dc18cf3c7776"

drive_id · string<uuid> · required

Drive ID where the project is located

Example:

"c9c5c47e-158a-49f7-846b-4f6ee2a229a2"

project_id · string<uuid> · required

Project ID (newly created or existing)

Example:

"9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"

project_url · string<uri> · required

URL to access the project in Descript web app

Example:

"https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"