Output paths

Choose where video asset and Transcoding outputs go in your storage.

The storage output prefix applies to video asset and Transcoding outputs. A video asset uses a folder template; a transcode uses the output filename you request.

Storage output prefix

In your storage configuration you can set an output prefix, named base_prefix in the API. For example, media/ places generated files below that prefix; an empty prefix writes them at the bucket root. This prefix only applies to output files.

Chunkify stores a nonempty prefix with a trailing slash, so media and media/ select the same folder.

Changing the prefix does not move existing files. A video asset saves its full output folder when it is created, so later outputs stay there. A transcode also saves its output prefix at creation.

Video asset output folders

Path template

Set Asset path template in Settings → Streaming to choose the output folder for future video assets. The API setting is asset_defaults.path_template on the Project. Updating asset_defaults replaces the whole defaults object, so include the other settings you want to keep.

An individual video asset can override the Project default with path_template when it is created. If neither is set, Chunkify uses {assetID}. The resolved folder is relative to the selected output storage's base_prefix. Source and Upload input locations are independent.

Chunkify temporary storage always uses {assetID}/ and does not use a custom template or require template metadata.

Template variables and rules

Templates support literal text, {assetID}, and {metadata.<key>}. Metadata is a flat map of strings with case-sensitive keys. There are no nested-object lookups or expressions.

With metadata.VideoID set to video-123 and a video asset ID of ast_2G6MJiNz71bHQGNzGwKx5cJwPFS:

Template	Relative output folder
`{assetID}`	`ast_2G6MJiNz71bHQGNzGwKx5cJwPFS/`
`videos/{metadata.VideoID}`	`videos/video-123/`
`videos/{metadata.VideoID}/{assetID}`	`videos/video-123/ast_2G6MJiNz71bHQGNzGwKx5cJwPFS/`

Unknown variables and malformed placeholders are rejected. Referenced metadata must exist and be non-empty. Slashes in a metadata value create subfolders, so series/episode-1 remains series/episode-1. Values are substituted once; text such as {assetID} inside a metadata value stays literal.

Expanded video asset folders cannot have leading or repeated slashes, . or .. segments, backslashes, URL schemes, query strings, fragments, or control characters. Chunkify does not rewrite identifiers. A single trailing slash is accepted.

Templates can contain up to 1,024 UTF-8 bytes. The complete expanded prefix, including the storage output prefix and trailing slash, can contain up to 768 bytes. The remaining 256 bytes are reserved for generated directories and filenames within the 1,024-byte object-key limit.

Create a video asset with a custom folder

Run these examples on your server with customer storage set as the Project default. Chunkify temporary storage ignores custom templates. Replace src_2G6MJiNz71bHQGNzGwKx5cJwPFS with an existing Source ID.

import Chunkify from '@chunkify/chunkify';

const client = new Chunkify({ projectAccessToken: process.env.CHUNKIFY_PROJECT_TOKEN });
const asset = await client.assets.create({
    source_id: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
    path_template: 'videos/{metadata.VideoID}',
    metadata: { VideoID: 'video-123' },
});
import os
from chunkify import Chunkify

client = Chunkify(project_access_token=os.environ["CHUNKIFY_PROJECT_TOKEN"])
asset = client.assets.create(
    source_id="src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
    path_template="videos/{metadata.VideoID}",
    metadata={"VideoID": "video-123"},
)
use Chunkify\Client;

$client = new Client(projectAccessToken: getenv('CHUNKIFY_PROJECT_TOKEN'));
$asset = $client->assets->create(
    sourceID: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
    pathTemplate: 'videos/{metadata.VideoID}',
    metadata: ['VideoID' => 'video-123'],
);
import (
	"context"
	"fmt"
	"os"

	"github.com/chunkifydev/chunkify-go"
	"github.com/chunkifydev/chunkify-go/option"
)

client := chunkify.NewClient(
	option.WithProjectAccessToken(os.Getenv("CHUNKIFY_PROJECT_TOKEN")),
)
asset, err := client.Assets.New(context.Background(), chunkify.AssetNewParams{
	SourceID:     "src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
	PathTemplate: chunkify.String("videos/{metadata.VideoID}"),
	Metadata:     map[string]string{"VideoID": "video-123"},
})
if err != nil {
	panic(err)
}

fmt.Println(asset.ID)

If the selected storage has an output prefix of media/, this call saves the HLS master playlist at:

media/videos/video-123/manifest.m3u8

Chunkify resolves the template once and saves the destination with the video asset. HLS renditions and manifests, posters, timeline previews, and static renditions use that folder. Static renditions added later use the same saved destination. Changing Project settings or video asset metadata does not move existing files or change their object keys.

Generated object paths

For a template that also includes the video asset ID, suppose the storage prefix is media/, the template is videos/{metadata.VideoID}/{assetID}, VideoID is video-123, and the video asset ID is ast_2G6MJiNz71bHQGNzGwKx5cJwPFS. Its output folder is:

media/videos/video-123/ast_2G6MJiNz71bHQGNzGwKx5cJwPFS/

Chunkify writes the HLS master playlist at media/videos/video-123/ast_2G6MJiNz71bHQGNzGwKx5cJwPFS/manifest.m3u8, the poster at media/videos/video-123/ast_2G6MJiNz71bHQGNzGwKx5cJwPFS/poster.jpg, and the timeline preview index at media/videos/video-123/ast_2G6MJiNz71bHQGNzGwKx5cJwPFS/thumbnails/images.vtt. HLS renditions, thumbnail images, and later static renditions or captions also belong to this folder.

These are object keys inside the bucket, not playback URLs. The video asset response exposes core playback, poster, and default timeline paths. Read Asset outputs for the paths of static renditions, captions, and additional thumbnails. Your application does not need to guess their filenames.

Folder ownership and conflicts

Chunkify reserves each video asset output folder against other video assets in the same storage. Creation returns HTTP 409 if another video asset owns the same folder, a parent folder, or a child folder. For example, videos/123/ conflicts with videos/123/hd/, but not with videos/1234/. Sibling folders succeed, and equal paths in different storage connections are independent. Concurrent requests cannot claim overlapping folders.

The check uses existing video asset records only. It does not check standalone Jobs or objects already in the bucket. A Job can write into a video asset's folder, and matching keys can be overwritten. Deleting a video asset with delete_files=true removes objects under its saved prefix, including any unrelated files there. Choose separate folders for standalone Jobs.

Video assets created from uploads

With create_asset: true, create the Upload session on your server and include every metadata key referenced by the Project template. For videos/{metadata.VideoID}, provide metadata: { VideoID: 'video-123' }. Missing or empty values are rejected before upload credentials are returned. With create_asset: false, these video asset metadata requirements do not apply.

The Upload saves the Project template and output settings when the session is created. Later Project changes do not affect it. Pass the returned Upload session to Chunkify Uploader, which handles transfer and completion.

No folder is reserved during transfer. At completion, Chunkify creates the video asset and checks folder ownership atomically. A conflict returns HTTP 409, marks the Upload failed with the reason, and emits upload.failed. Source creation, video asset creation, and usage changes from that completion are rolled back. Further completion calls follow the terminal failure behavior and return a validation error. Correct the metadata or Project template and create a new Upload session.

Transcode output paths

A transcode writes its output to the Project default storage unless you override storage.id. The input Source can use another storage configuration.

For your storage, supply storage.path as a filename relative to base_prefix. The extension must match the resolved output: .mp4, .webm, or .m4a.

With base_prefix: media/ and storage.path: exports/video.mp4, the final key is media/exports/video.mp4. Do not include the prefix twice. Video asset folder templates do not apply to Transcodings.

These examples use an existing Source and the Project default output storage:

import Chunkify from '@chunkify/chunkify';

async function main() {
    const client = new Chunkify({
        projectAccessToken: 'My Project Access Token',
    });

    const transcoding = await client.transcodings.create({
        source_id: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
        format: {
            id: "mp4_h264",
        },
        storage: {
            path: 'exports/video.mp4',
        },
    });

    console.log(transcoding.id, transcoding.status);
}

main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});
from chunkify import Chunkify

client = Chunkify(
    project_access_token="My Project Access Token",
)

transcoding = client.transcodings.create(
    source_id="src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
    format={
        "id": "mp4_h264",
    },
    storage={
        "path": "exports/video.mp4",
    },
)

print(transcoding.id, transcoding.status)
<?php

use Chunkify\Client;

require_once __DIR__ . '/vendor/autoload.php';

$client = new Client(
    projectAccessToken: 'My Project Access Token',
);

$transcoding = $client->transcodings->create(
    sourceID: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
    format: [
        'id' => 'mp4_h264',
    ],
    storage: [
        'path' => 'exports/video.mp4',
    ],
);

var_dump($transcoding->id, $transcoding->status);
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/chunkifydev/chunkify-go"
	"github.com/chunkifydev/chunkify-go/option"
)

func main() {
	client := chunkify.NewClient(
		option.WithProjectAccessToken("My Project Access Token"),
	)

	transcoding, err := client.Transcodings.New(
		context.Background(),
		chunkify.TranscodingNewParams{
			SourceID: "src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
			Format: chunkify.TranscodingNewParamsFormatUnion{
				OfMP4H264: &chunkify.TranscodingMP4H264Param{},
			},
			Storage: chunkify.TranscodingNewParamsStorage{
				Path: chunkify.String("exports/video.mp4"),
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(transcoding.ID, transcoding.Status)
}

The transcode saves its prefix when created, so changing the storage prefix later does not move its files. Use a distinct filename for each export.

Chunkify temporary storage generates the path automatically and deletes outputs 24 hours after publication. See Lifecycle and files.

Legacy Job output paths

Legacy Jobs use the storage prefix at upload time, so later prefix changes can affect their pending output.

For a transcoding Job using your storage, you are required to set storage.path to the output filename and its folder relative to that storage configuration prefix.

Video asset path templates do not affect transcode jobs.

Suppose your connected storage has these settings (other fields omitted):

{
  "id": "stor_aws_2G6MJiNz71bHQGNzGwKx5cJwPFS",
  "base_prefix": "media/"
}

Create the Job with a path relative to that prefix:

import Chunkify from '@chunkify/chunkify';

const client = new Chunkify({ projectAccessToken: 'My Project Access Token' });
const job = await client.jobs.create({
  source_id: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
  format: { id: 'mp4_h264' },
  storage: {
    id: 'stor_aws_2G6MJiNz71bHQGNzGwKx5cJwPFS',
    path: 'exports/video.mp4',
  },
});
from chunkify import Chunkify

client = Chunkify(project_access_token="My Project Access Token")
job = client.jobs.create(
    source_id="src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
    format={"id": "mp4_h264"},
    storage={
        "id": "stor_aws_2G6MJiNz71bHQGNzGwKx5cJwPFS",
        "path": "exports/video.mp4",
    },
)
use Chunkify\Client;

$client = new Client(projectAccessToken: 'My Project Access Token');
$job = $client->jobs->create(
    sourceID: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
    format: ['id' => 'mp4_h264'],
    storage: [
        'id' => 'stor_aws_2G6MJiNz71bHQGNzGwKx5cJwPFS',
        'path' => 'exports/video.mp4',
    ],
);
import (
    "context"

    "github.com/chunkifydev/chunkify-go"
    "github.com/chunkifydev/chunkify-go/option"
)

client := chunkify.NewClient(
    option.WithProjectAccessToken("My Project Access Token"),
)
_, err := client.Jobs.New(context.Background(), chunkify.JobNewParams{
    SourceID: "src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
    Format: chunkify.JobNewParamsFormatUnion{
        OfMP4H264: &chunkify.MP4H264Param{},
    },
    Storage: chunkify.JobNewParamsStorage{
        ID:   chunkify.String("stor_aws_2G6MJiNz71bHQGNzGwKx5cJwPFS"),
        Path: chunkify.String("exports/video.mp4"),
    },
})
if err != nil {
    panic(err)
}

Chunkify writes the output at media/exports/video.mp4. Do not include media/ in storage.path; Chunkify adds it automatically.

Use a filename that matches the format, such as .mp4, .webm, .m3u8, or .vtt. A JPG image sequence needs %05d in its .jpg filename. Chunkify removes leading slashes for compatibility, but write paths without them.

HLS caption Jobs in a manifest group must use the same output folder as the group's other Jobs. Keep unrelated Jobs in separate folders to avoid replacing existing files. When using Chunkify temporary storage, Chunkify chooses the Job output path.