Skip to main content
POST
/
api
/
v1
/
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"
  }'

{
  "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

​
name
string
required
Display name of the artifact. E.g., My Project Video.
​
type
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:
​
s3Path
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
​
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
​
fragments
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
  • startTime - start time in seconds (must be >= 0)
All fragments must have the same format (codec, resolution, frame rate).Use when: Combining multiple clips into one file
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:
​
id
string
Unique identifier for the artifact. Use this to retrieve artifact status or use in other endpoints.
​
name
string
Display name of the artifact.
​
type
string
Type of artifact: video, audio, or script.
​
status
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)
​
uploadMethod
string
Upload method used:
  • direct_url - Presigned upload, direct URL, or S3 path
  • fragments - Fragment concatenation
​
size
number | null
File size in bytes. Will be null until processing completes.
​
duration
number | null
Duration in seconds (for video/audio). Will be null until processing completes or for script type.
​
errorMessage
string | null
Error message if processing failed. Will be null unless status is upload_failed.
​
s3Path
string
Internal S3 path where the artifact file is stored (without bucket prefix).
​
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.
​
createdBy
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"
  }'

{
  "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

1

Create Artifact

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

Background Processing

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

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
4

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.

​
See Also