Create Artifact

# After uploading file via 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": "My Source Video",
    "type": "video",
    "s3Path": "s3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Marketing Video",
    "type": "video",
    "url": "https://cdn.example.com/videos/promo.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Archive Video",
    "type": "video",
    "s3Path": "s3://my-company-bucket/recordings/meeting-2024.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Concatenated Video",
    "type": "video",
    "fragments": [
      {
        "url": "https://example.com/intro.mp4",
        "timePositionMs": 0
      },
      {
        "url": "https://example.com/main.mp4",
        "timePositionMs": 10000
      },
      {
        "url": "https://example.com/outro.mp4",
        "timePositionMs": 300000
      }
    ]
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Trimmed and Concatenated Audio",
    "type": "audio",
    "fragments": [
      {
        "url": "https://example.com/full-recording.wav",
        "timePositionMs": 0,
        "timeInMs": 5000,
        "timeOutMs": 15000
      },
      {
        "url": "https://example.com/full-recording.wav",
        "timePositionMs": 10000,
        "timeInMs": 60000,
        "timeOutMs": 90000
      }
    ]
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Concatenated Audio",
    "type": "audio",
    "fragments": [
      {
        "url": "https://example.com/segment1.wav",
        "timePositionMs": 0
      },
      {
        "url": "https://example.com/segment2.wav",
        "timePositionMs": 120500
      }
    ],
    "artifactDurationMs": 360000
  }'

const response = await fetch(
  'https://studio.dubformer.ai/api/v1/artifacts/create',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'My Source Video',
      type: 'video',
      s3Path: 's3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4'
    })
  }
);

const artifact = await response.json();
console.log(artifact);

import requests

response = requests.post(
    'https://studio.dubformer.ai/api/v1/artifacts/create',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'My Source Video',
        'type': 'video',
        's3Path': 's3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4'
    }
)

artifact = response.json()
print(artifact)

{
  "id": "67a8f9b0c1d2e3f4g5h6i7j8",
  "name": "My Source Video",
  "type": "video",
  "status": "created",
  "uploadMethod": "direct_url",
  "size": null,
  "duration": null,
  "errorMessage": null,
  "s3Path": "uploads/67a8f9b0c1d2e3f4g5h6i7j8/video.mp4",
  "s3Bucket": "dubformer-artifacts",
  "createdAt": "2026-02-04T12:00:00.000Z",
  "updatedAt": "2026-02-04T12:00:00.000Z",
  "company": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Acme Inc"
  },
  "createdBy": {
    "id": "507f191e810c19729de860ea",
    "name": "John Doe"
  }
}

POST

api

artifacts

create

# After uploading file via 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": "My Source Video",
    "type": "video",
    "s3Path": "s3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Marketing Video",
    "type": "video",
    "url": "https://cdn.example.com/videos/promo.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Archive Video",
    "type": "video",
    "s3Path": "s3://my-company-bucket/recordings/meeting-2024.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Concatenated Video",
    "type": "video",
    "fragments": [
      {
        "url": "https://example.com/intro.mp4",
        "timePositionMs": 0
      },
      {
        "url": "https://example.com/main.mp4",
        "timePositionMs": 10000
      },
      {
        "url": "https://example.com/outro.mp4",
        "timePositionMs": 300000
      }
    ]
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Trimmed and Concatenated Audio",
    "type": "audio",
    "fragments": [
      {
        "url": "https://example.com/full-recording.wav",
        "timePositionMs": 0,
        "timeInMs": 5000,
        "timeOutMs": 15000
      },
      {
        "url": "https://example.com/full-recording.wav",
        "timePositionMs": 10000,
        "timeInMs": 60000,
        "timeOutMs": 90000
      }
    ]
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Concatenated Audio",
    "type": "audio",
    "fragments": [
      {
        "url": "https://example.com/segment1.wav",
        "timePositionMs": 0
      },
      {
        "url": "https://example.com/segment2.wav",
        "timePositionMs": 120500
      }
    ],
    "artifactDurationMs": 360000
  }'

const response = await fetch(
  'https://studio.dubformer.ai/api/v1/artifacts/create',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'My Source Video',
      type: 'video',
      s3Path: 's3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4'
    })
  }
);

const artifact = await response.json();
console.log(artifact);

import requests

response = requests.post(
    'https://studio.dubformer.ai/api/v1/artifacts/create',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'My Source Video',
        'type': 'video',
        's3Path': 's3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4'
    }
)

artifact = response.json()
print(artifact)

{
  "id": "67a8f9b0c1d2e3f4g5h6i7j8",
  "name": "My Source Video",
  "type": "video",
  "status": "created",
  "uploadMethod": "direct_url",
  "size": null,
  "duration": null,
  "errorMessage": null,
  "s3Path": "uploads/67a8f9b0c1d2e3f4g5h6i7j8/video.mp4",
  "s3Bucket": "dubformer-artifacts",
  "createdAt": "2026-02-04T12:00:00.000Z",
  "updatedAt": "2026-02-04T12:00:00.000Z",
  "company": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Acme Inc"
  },
  "createdBy": {
    "id": "507f191e810c19729de860ea",
    "name": "John Doe"
  }
}

This endpoint creates an artifact record and initiates file processing. Use this endpoint after uploading a file via presigned URL, or directly with external URLs/S3 paths.

Uploading a local file? First get a presigned URL using Get Presigned Upload URL, upload your file, then use this endpoint with the S3 path.

Can handle files up to 5GB.

Observe your artifacts

View and track all your artifacts and their processing status in real-time via the Artifacts Dashboard.

Request Body

string

required

Display name of the artifact. E.g., My Project Video.

string

required

Type of artifact. Must be one of:

video - Video files
audio - Audio files
script - Text/script files

Source Parameters

Choose exactly one of the following parameters to specify your file source:

string

S3 path to the file. Can be:

Path from Get Presigned Upload URL (e.g., s3://dubformer-temp/uploads/aafa1753/file.mp4)
External S3 bucket path (e.g., s3://my-bucket/path/to/file.mp4) - requires S3 credentials configured

Use when: File is already in S3 or uploaded via presigned URL

string

Direct URL to download the artifact from an external source.Must be a publicly accessible URL. The file will be downloaded asynchronously.Use when: File is hosted on a CDN, public storage, or web server

array

Array of media fragments to concatenate into a single artifact.Not supported for script type. Each fragment object must contain:

url or s3Path - source location
timePositionMs - start time in milliseconds (must be >= 0)

Optional trimming fields (audio only):

timeInMs - trim start position within the source file in milliseconds (must be >= 0). If omitted, trimming starts from the beginning
timeOutMs - trim end position within the source file in milliseconds (must be > timeInMs when both are provided). If omitted, trimming goes to the end

When specified, only the matching portion is extracted from the source and placed at timePositionMs in the final artifact.All fragments must have the same format (codec, resolution, frame rate). Fragments are sorted by timePositionMs and gaps between them are filled with silence (audio) or black frames (video).Use when: Combining multiple clips (or portions of clips) into one file

number

Target duration of the final artifact in milliseconds. Can only be used with audio type fragments.When specified, the concatenated result is adjusted to match this exact duration:

If the result is shorter, silence is appended
If the result is longer, it is trimmed

Use when: You need the audio artifact to have a precise duration (e.g., matching a source video length)

Using external AWS S3? To enable external S3 paths or S3 fragments, configure AWS credentials for your API key in Dashboard Settings → API Keys → Select your key → S3 Credentials.

Response

Returns a complete artifact object:

string

Unique identifier for the artifact. Use this to retrieve artifact status or use in other endpoints.

string

Display name of the artifact.

string

Type of artifact: video, audio, or script.

string

Current processing status. Possible values:

created - Artifact created, processing pending
upload_started - File is being downloaded/copied/processed
upload_completed - File is ready for use
upload_failed - Processing failed (check errorMessage)

string

Upload method used:

direct_url - Presigned upload, direct URL, or S3 path
fragments - Fragment concatenation

number | null

File size in bytes. Will be null until processing completes.

number | null

Duration in seconds (for video/audio). Will be null until processing completes or for script type.

string | null

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

string

Internal S3 path where the artifact file is stored (without bucket prefix).

string

S3 bucket name where the artifact is stored.

string

ISO 8601 timestamp when the artifact was created.

string

ISO 8601 timestamp when the artifact was last updated.

object | undefined

Company information object containing id and name fields.

object | undefined

User information object containing id and name fields for the user who created the artifact.

Request Examples

# After uploading file via 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": "My Source Video",
    "type": "video",
    "s3Path": "s3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Marketing Video",
    "type": "video",
    "url": "https://cdn.example.com/videos/promo.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Archive Video",
    "type": "video",
    "s3Path": "s3://my-company-bucket/recordings/meeting-2024.mp4"
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Concatenated Video",
    "type": "video",
    "fragments": [
      {
        "url": "https://example.com/intro.mp4",
        "timePositionMs": 0
      },
      {
        "url": "https://example.com/main.mp4",
        "timePositionMs": 10000
      },
      {
        "url": "https://example.com/outro.mp4",
        "timePositionMs": 300000
      }
    ]
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Trimmed and Concatenated Audio",
    "type": "audio",
    "fragments": [
      {
        "url": "https://example.com/full-recording.wav",
        "timePositionMs": 0,
        "timeInMs": 5000,
        "timeOutMs": 15000
      },
      {
        "url": "https://example.com/full-recording.wav",
        "timePositionMs": 10000,
        "timeInMs": 60000,
        "timeOutMs": 90000
      }
    ]
  }'

curl -X POST \
  https://studio.dubformer.ai/api/v1/artifacts/create \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Concatenated Audio",
    "type": "audio",
    "fragments": [
      {
        "url": "https://example.com/segment1.wav",
        "timePositionMs": 0
      },
      {
        "url": "https://example.com/segment2.wav",
        "timePositionMs": 120500
      }
    ],
    "artifactDurationMs": 360000
  }'

const response = await fetch(
  'https://studio.dubformer.ai/api/v1/artifacts/create',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'My Source Video',
      type: 'video',
      s3Path: 's3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4'
    })
  }
);

const artifact = await response.json();
console.log(artifact);

import requests

response = requests.post(
    'https://studio.dubformer.ai/api/v1/artifacts/create',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'My Source Video',
        'type': 'video',
        's3Path': 's3://dubformer-artifacts/temp/550e8400-e29b-41d4-a716-446655440000/video.mp4'
    }
)

artifact = response.json()
print(artifact)

{
  "id": "67a8f9b0c1d2e3f4g5h6i7j8",
  "name": "My Source Video",
  "type": "video",
  "status": "created",
  "uploadMethod": "direct_url",
  "size": null,
  "duration": null,
  "errorMessage": null,
  "s3Path": "uploads/67a8f9b0c1d2e3f4g5h6i7j8/video.mp4",
  "s3Bucket": "dubformer-artifacts",
  "createdAt": "2026-02-04T12:00:00.000Z",
  "updatedAt": "2026-02-04T12:00:00.000Z",
  "company": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Acme Inc"
  },
  "createdBy": {
    "id": "507f191e810c19729de860ea",
    "name": "John Doe"
  }
}

Processing Workflow

Create Artifact

Send a POST request with one of the source parameters (s3Path, url, or fragments).The artifact is created with created status.

Background Processing

The file is downloaded/copied/processed asynchronously.Status transitions to upload_started during processing.

Completion

When processing completes:

Status becomes upload_completed (success) or upload_failed (error)
size and duration fields are populated
If failed, check errorMessage for details

Monitor Status

Use Get Artifact to check processing status:

GET /api/v1/artifacts/{artifactId}

Artifact processing happens asynchronously. The artifact is created immediately, but the file may not be ready for use until status is upload_completed. Always check the status before using the artifact.

Getting Started

Artifacts

Projects

Project Videos

Observe your artifacts

Request Body

Source Parameters

Response

Request Examples

Processing Workflow

See Also

Observe your artifacts

​Request Body

​Source Parameters

​Response

​Request Examples

​Processing Workflow

​See Also

Request Body

Source Parameters

Response

Request Examples

Processing Workflow

See Also