Create & Upload Artifact

Create a new artifact and upload a source file

POST https://studio.dubformer.ai/api/v1/artifacts/create

Request (Presigned URL)

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "source_video.mp4",
    "type": "video"
  }'

Response (Presigned URL)

{
  "artifactId": "67a8f9b0c1d2e3f4g5h6i7j8",
  "presignedUploadUrl": "https://storage.dubformer.ai/uploads/67a8f9b0c1d2e3f4g5h6i7j8/source_video.mp4?X-Amz-Algorithm=...",
  "expiresAt": "2026-01-12T12:30:00.000Z"
}

Request Body

Can handle files up to 5GB.

name · string · required

Name of the artifact being uploaded. E.g. source_video.mp4

type · string · required

Type of artifact being uploaded. Must be one of: video, audio, or script.

Upload Methods

Choose one of the following methods to provide your source file:

1. Presigned URL (recommended for local files)

Don’t include any source parameters (url, s3Path, or fragments). We’ll return a temporary presigned URL that you can use to upload your file directly to our storage using a PUT request.

Best for: Uploading files from your local machine or when you need full control over the upload process.

2. Direct URL (download from web)

Provide a url parameter with a publicly accessible link to your file. We’ll download the file asynchronously from the provided URL.

Best for: When your file is already hosted somewhere (CDN, public cloud storage, etc.) and you want us to fetch it.

url · string

Direct URL to download the artifact from an external source. Mutually exclusive with s3Path and fragments.

3. S3 Path (copy from your S3 bucket)

Provide an s3Path parameter pointing to a file in your AWS S3 bucket (e.g., s3://my-bucket/path/to/video.mp4). We’ll copy the file directly from your S3 storage without downloading/re-uploading.

Best for: Files already stored in S3. This is the fastest method as it avoids internet transfers.

Setup required: You must first attach AWS S3 credentials to your API key in your dashboard settings.

s3Path · string

S3 path to the artifact in your configured S3 storage. Requires S3 credentials to be configured for your API key. Mutually exclusive with url and fragments.

4. Fragments (concatenate multiple clips)

Provide a fragments array with multiple video/audio clips. We’ll fetch each fragment (from URL or S3) and concatenate them into a single artifact. Each fragment must specify either url or s3Path, plus a startTime.

Best for: Combining multiple clips into one file before processing.

Limitations: Not supported for script type artifacts. All fragments must be in the same format (codec, resolution, frame rate).

fragments · array

Array of media fragments to concatenate into a single artifact. Not supported for script type. Mutually exclusive with url and s3Path. Each fragment must contain:

• Either url (string) OR s3Path (string) - source location of the fragment
• startTime (number) - start time in seconds (must be >= 0)

Using AWS S3? To enable S3 uploads (method 3) or S3 fragments (method 4), attach your AWS credentials to your API key. You can configure this in your dashboard settings under API Keys → Select your key → S3 Credentials.

Response

Presigned Upload Response

artifactId · string

Unique identifier for the created artifact.

presignedUploadUrl · string

Presigned S3 URL for uploading the file via PUT request. Valid for limited time.

expiresAt · string

ISO 8601 timestamp when the presigned upload URL expires (typically 15 minutes from creation).

Direct URL, S3 Path, and Fragments Response

Returns a complete artifact object with the following fields:

id · string

Unique identifier for the artifact.

fileName · string

Name of the uploaded file.

type · string

Type of artifact: video, audio, or script.

status · string

Current processing status. Initial value is created. Will change to ready, failed, or other states as processing progresses.

uploadMethod · string

Upload method used: direct_url (for Direct URL and S3 Path methods) or fragments (for Fragment concatenation).

size · number | null

File size in bytes. Will be null until the file is processed.

duration · number | null

Duration in seconds (for video/audio). Will be null until the file is processed or for script type.

errorMessage · string | null

Error message if processing failed. Will be null unless status is failed.

s3Path · string

Internal S3 path where the artifact is stored.

s3Bucket · string

S3 bucket name where the artifact is stored.

createdAt · string

ISO 8601 timestamp when the artifact was created.

updatedAt · string

ISO 8601 timestamp when the artifact was last updated.

company · object | undefined

Company information object containing id and name fields. May be undefined depending on context.

createdBy · object | undefined

User information object containing id and name fields for the user who created the artifact. May be undefined depending on context.

Request (Presigned URL)

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "source_video.mp4",
    "type": "video"
  }'

Response (Presigned URL)

{
  "artifactId": "67a8f9b0c1d2e3f4g5h6i7j8",
  "presignedUploadUrl": "https://storage.dubformer.ai/uploads/67a8f9b0c1d2e3f4g5h6i7j8/source_video.mp4?X-Amz-Algorithm=...",
  "expiresAt": "2026-01-12T12:30:00.000Z"
}

Upload Methods

Presigned Upload

When using presigned upload (no url, s3Path, or fragments in the request), you’ll receive a presignedUploadUrl. Upload your file using a PUT request:

curl -X PUT \
  "https://storage.dubformer.ai/uploads/1a2b3c4d5e6f7g8h9i0j?signed=..." \
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/your/source_video.mp4'

The upload URL is valid only for the specified time in the expiresAt field. Make sure to complete your upload before this time expires.

URL Upload

When providing a url parameter, the system will download the file from the specified URL asynchronously. The artifact will be created immediately with a pending status.

S3 Upload

When providing an s3Path parameter, the system will copy the file from your configured S3 storage. This requires S3 credentials to be configured for your API key.

Fragment Concatenation

When providing fragments, the system will download or copy each fragment and concatenate them into a single artifact. Each fragment must specify either a url or s3Path, and a startTime. This is not supported for script type artifacts.

For URL, S3, and Fragment uploads, the artifact processing happens asynchronously. Monitor the artifact status to know when processing is complete.