--- title: "Import media and sequences" method: POST path: "/jobs/import/project_media" tags: ["API Endpoints"] --- # Import media and sequences `POST /jobs/import/project_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](https://help.descript.com/hc/en-us/articles/10164098416909-Supported-file-types) ### Direct file upload Instead of providing a URL, you can upload files directly by specifying `content_type` and `file_size` for a media item. The response will include a signed `upload_url` for each direct upload item. PUT the file bytes to that URL, and the import job will process it automatically. See the [Direct file upload](#tag/Direct-file-upload) guide for a full walkthrough. ### Async Operations Imports run in the background and return a `job_id`. Monitor progress via the [GET /jobs/{job_id}](#operation/getJob) 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/{job_id}](#operation/getJob). ## Request body - object — 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 — 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. - `project_name` string — Name for the new project. Only used when project_id is not provided. - `team_access` 'edit' | 'comment' | 'view' | '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) - `folder_name` string — Folder path to place the new project in (e.g. "Clients/Acme/Videos"). Supports nested paths using "/" as separator. Only applicable when creating a new project (when project_id is not provided). Existing folders along the path are reused; missing segments are created automatically. - `workspace_name` string — Existing workspace to create the new project in, matched by name (case-insensitive). Only applicable when creating a new project (when project_id is not provided). Reserved names: `Personal` (your private space) and `General` (the shared drive workspace). Any other value is looked up as a custom workspace name; unknown names return 404. When omitted, `team_access` is passed through unchanged. When set to `Personal`, `team_access` must be `none` or omitted. When set to `General` or a custom workspace name, `team_access` must be `edit`, `comment`, or `view`; omitting it defaults to `view`, and `none` is rejected. For custom workspaces, the caller must be a member of that workspace. - `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). - `add_compositions` object[] — Optional list of compositions to create in the project - `name` string — Name of the composition. If not provided, uses default naming. - `width` integer — Width of the composition in pixels - `height` integer — Height of the composition in pixels - `fps` number — **[Work in progress]** This property is not yet supported and will be ignored if provided. Frame rate for the composition in frames per second. Common values: 24, 25, 29.97, 30, 60. - `clips` object[], required — Ordered list of clips to include in the composition - `media` string, required — Media reference ID (display name) of the media to add as a clip - `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}](#operation/getJob)) to this URL. ## Response `201` Import job created successfully - object — Response returned when creating an import job - `job_id` string, uuid, required — Unique identifier for the job - `drive_id` string, uuid, required — Drive ID where the project is located - `drive_name` string, nullable — Human-readable name of the connected drive (workspace) - `project_id` string, uuid, required — Project ID (newly created or existing) - `project_url` string, uri, required — URL to access the project in Descript web app - `upload_urls` object — Signed upload URLs for each direct upload media item. Only present when the request includes direct upload references. PUT the file contents to the `upload_url` with `Content-Type: application/octet-stream`. The import job will automatically detect the upload and process the file. ## Other responses - `400` — Invalid input: - Malformed request body - Invalid media URLs - URLs not accessible or don't support Range requests - Media filename conflicts with existing files (when importing to existing project) - `401` — Unauthorized - missing or invalid authentication token - `402` — Payment Required - insufficient media minutes to start the job - `403` — Forbidden - user does not have access to this resource - `404` — Not found: - Drive doesn't exist - Project doesn't exist (when project_id is provided) - `429` — Too many requests - rate limit exceeded. Use the `Retry-After` header to determine when to retry. ## Changes > 4 revisions in range; 1 could not be searched. - **2026-08-04** `e2ed99c3f802` — 1 info - added the new optional request property `workspace_name` [Change history](https://skmtc.dev/descriptapi/apis/descript-api/changes/jobs/import/project_media/post.md) --- [API](https://skmtc.dev/descriptapi/apis/descript-api.md) · [All operations](https://skmtc.dev/descriptapi/apis/descript-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/descriptapi/descript-api/revisions/04c0005aef70/schema)