Create an asset

posthttps://api.netflix.developers.gaudiolab.io/v1/assets

Starts an upload and returns an assetId to attach to a job. The upload object in the response tells you how to deliver the bytes — a single PUT, a multipart upload, or a server-side fetch when you pass sourceUrl. The asset becomes ready once its bytes are received.

post/assets

curl -X POST "https://api.netflix.developers.gaudiolab.io/v1/assets" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "movie_reel_01.wav",
    "fileSize": 1900000000
  }'

Response201

{
  "assetId": "as_7f3a9c",
  "status": "awaiting_upload",
  "fileName": "string",
  "format": "string",
  "sourceUrl": "https://...",
  "expiresAt": "2026-06-08T12:00:00Z",
  "upload": {
    "mode": "single",
    "url": "https://...",
    "chunkSize": 0,
    "parts": [
      {
        "partNumber": 0,
        "url": "https://..."
      }
    ],
    "completeUrl": "string"
  }
}

Headers

x-api-keyRequired

Your project API key, sent on every request. Create and manage keys in the dashboard under Settings → API Keys.

Request body

Provide one of: fileName + fileSize or sourceUrl

fileNamestringOptional

Name of the file you are uploading, including its extension. Used to infer the input format. Supported: WAV (.wav), AIFF (.aiff/.aif), FLAC (.flac), MP3 (.mp3), AAC (.aac/.m4a). For best results upload WAV at 16- or 24-bit, up to 192 kHz, mono or stereo. 5.1 (six-channel) input is accepted for DME targets only, and must be PCM WAV/RF64 carrying an explicit 5.1 channel layout.

fileSizeinteger (int64)Optional

Size of the file in bytes. Determines whether the response asks for a single-shot or a resumable multipart upload. Maximum 6 GB.

sourceUrlstring (uri)Optional

Publicly reachable URL of the media to ingest. When set, the server downloads the file and the upload step is skipped entirely. Mutually exclusive with fileName and fileSize.

Response

201The asset was created. Follow upload to deliver the bytes (unless you used sourceUrl).

assetIdstringRequired

Unique identifier for the asset. Pass it as assetId when creating a job.

statusenumRequired

Lifecycle state. awaiting_upload until the bytes are received, then ready to be used in a job, and expired after 72 hours.

Allowed values: awaiting_uploadreadyexpired

fileNamestringOptional

The file name this asset was created with.

formatstringOptional

Audio format detected from the file (e.g. wav, mp3, aac).

sourceUrlstring (uri)Optional

Presigned GET URL for the stored source audio (remote-URL assets echo the URL you provided). Returned by GET /assets/{assetId} and the multipart complete response; null on the create response since nothing is downloadable yet.

expiresAtstring (date-time)Optional

ISO 8601 timestamp at which the asset and its bytes are deleted. Assets are retained for 72 hours after upload.

uploadUploadInstructionOptional

How to deliver the file's bytes. Present only while the asset's status is awaiting_upload.

modeenumRequired

single: one PUT to url. multipart: PUT each chunk in parts, then call completeUrl. remote: nothing to do — the server is fetching your sourceUrl.

Allowed values: singlemultipartremote

urlstring (uri)Optional

Pre-signed URL to PUT the entire file to. Single mode only.

chunkSizeintegerOptional

Size in bytes to split the file into before uploading. Multipart mode only.

partsobject[]Optional

Ordered list of pre-signed URLs, one per chunk. Multipart mode only.

partNumberintegerRequired

1-based index of the chunk.

urlstring (uri)Required

Pre-signed URL to PUT this chunk to.

completeUrlstringOptional

Path to call once every chunk has been uploaded. Multipart mode only.

400The request was malformed or failed validation.

codestringRequired

A stable, machine-readable error code you can branch on.

messagestringRequired

A human-readable explanation of what went wrong.

401The API key is missing or invalid.

codestringRequired

A stable, machine-readable error code you can branch on.

messagestringRequired

A human-readable explanation of what went wrong.

413The file exceeds the 6 GB limit.

codestringRequired

A stable, machine-readable error code you can branch on.

messagestringRequired

A human-readable explanation of what went wrong.