Setup

Pass an Upload session through the component's upload JavaScript property or React prop. Your server creates the session with the Chunkify SDK; the component handles transfer and completion in the browser.

Use an async provider to create a session after file selection. See Get started for the browser function and HTML or React interface.

Create the Upload on your server

Your application route receives filename and file_size_bytes from the browser provider. Authorize the current user, validate the file size, and choose a unique object key and application video ID on your server.

The helper below creates a session using your Project's default storage and requests a video asset after completion. objectKey includes the original's filename, such as incoming/video-123/original.mp4.

The Upload's storage.path selects where the original goes. The video asset's generated files use the Project's default output settings. For Chunkify temporary storage, omit storage.

To select another storage configuration for the original, add storage.id alongside path. See Choose where to upload for the storage rules.

import Chunkify from '@chunkify/chunkify';

export async function createUploadSession(
    fileSizeBytes: number,
    objectKey: string,
    videoId: string,
) {
    const client = new Chunkify({
        projectAccessToken: process.env.CHUNKIFY_PROJECT_TOKEN,
    });

    return client.uploads.create({
        upload_mode: 'auto',
        file_size_bytes: fileSizeBytes,
        create_asset: true,
        storage: {
            path: objectKey,
        },
        metadata: {
            VideoID: videoId,
        },
    });
}

import os
from chunkify import Chunkify


def create_upload_session(file_size_bytes, object_key, video_id):
    client = Chunkify(
        project_access_token=os.environ["CHUNKIFY_PROJECT_TOKEN"],
    )

    return client.uploads.create(
        upload_mode="auto",
        file_size_bytes=file_size_bytes,
        create_asset=True,
        storage={
            "path": object_key,
        },
        metadata={
            "VideoID": video_id,
        },
    )

<?php

use Chunkify\Client;
use Chunkify\Uploads\Upload;

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

function createUploadSession(
    int $fileSizeBytes,
    string $objectKey,
    string $videoID,
): Upload {
    $client = new Client(
        projectAccessToken: getenv('CHUNKIFY_PROJECT_TOKEN'),
    );

    return $client->uploads->create(
        uploadMode: 'auto',
        fileSizeBytes: $fileSizeBytes,
        createAsset: true,
        storage: [
            'path' => $objectKey,
        ],
        metadata: [
            'VideoID' => $videoID,
        ],
    );
}

package main

import (
	"context"
	"os"

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

func createUploadSession(fileSizeBytes int64, objectKey, videoID string) (*chunkify.Upload, error) {
	client := chunkify.NewClient(
		option.WithProjectAccessToken(os.Getenv("CHUNKIFY_PROJECT_TOKEN")),
	)

	return client.Uploads.New(
		context.Background(),
		chunkify.UploadNewParams{
			UploadMode:    chunkify.UploadNewParamsUploadModeAuto,
			FileSizeBytes: chunkify.Int(fileSizeBytes),
			CreateAsset:   chunkify.Bool(true),
			Storage: chunkify.UploadNewParamsStorage{
				Path: chunkify.String(objectKey),
			},
			Metadata: map[string]string{
				"VideoID": videoID,
			},
		},
	)
}

auto chooses single PUT at or below 100 MiB and multipart above it. Always send the selected file's exact size as file_size_bytes. The component uses the returned mode; it does not choose the threshold.

Set upload_mode to single or multipart to require one mode. A multipart creation failure does not automatically switch to single PUT. Check your provider's multipart support.

Omit create_asset or set it to false if you only need a Source. filename is an application request field, not a Chunkify API field. Do not trust a browser-supplied destination key or storage ID without checking it.

Keep your Project token on the server. Save the Upload ID with your application record to correlate webhook events.

Return the session to the browser

Serialize only the fields needed by the uploader from the SDK's returned Upload. Return the object directly, without a data wrapper, and set Cache-Control: no-store on your application response.

For example, after calling createUploadSession() in a TypeScript route, build its JSON response from these fields:

const upload = await createUploadSession(fileSizeBytes, objectKey, videoId);

const session = upload.upload_mode === 'multipart'
    ? {
        upload_mode: upload.upload_mode,
        completion_url: upload.completion_url,
        expires_at: upload.expires_at,
        multipart: upload.multipart,
    }
    : {
        upload_mode: upload.upload_mode,
        upload_url: upload.upload_url,
        completion_url: upload.completion_url,
        expires_at: upload.expires_at,
    };

Return expiry timestamps and the complete multipart object unchanged. It contains part_size_bytes, every signed part URL with its part_number, and the part URLs' expires_at timestamp.

The package exports UploadSession, SingleUploadSession, and MultipartUploadSession types. Use a type-only import in TypeScript browser code:

import type { UploadSession } from '@chunkify/uploader';

The component accepts one session per file. You can supply an existing session object as uploader.upload = session or upload={session}. After resetting, provide a new session before selecting another file.

Transfer and completion

The component slices the file, collects ETags, and sends the completed part list for you. You do not need to implement those steps in your browser application.

Progress measures bytes transferred across the whole file. It stays at 100% while completion runs. Success requires 204 No Content; the completion request sends no Project token or cookies.

Completion and retries

Each transfer or completion request gets up to three total attempts for network failures, timeouts, HTTP 408, 429, and 5xx responses. Delays start at 500 ms, then one second.

A readable Retry-After header can extend the delay to 30 seconds. A larger delay stops automatic retries. Completion requests time out after 30 seconds; file transfers time out after 120 seconds without progress.

After those attempts fail, the Retry control continues the failed step using the same file and session. Completed multipart parts are retained. Once all bytes have transferred, Retry only repeats completion.

The retryable attribute indicates that manual recovery is possible. HTTP 403 is not retried automatically, but you can retry after correcting permissions. A missing ETag can be retried after fixing storage CORS.

A known expiration, HTTP 410, or another non-recoverable client error requires starting over with a new session. If the provider failed before returning a valid session, Retry calls it again with the retained file.

Retry state stays in memory while the component remains mounted. Resetting, removing the component, or reloading the page discards the selected file, session, and completed part records.

Single-PUT sessions default to two hours. Multipart defaults depend on file size and range from two to 48 hours. Transfers and completion must finish before expiry. See expiration.

Browser CORS configuration

The browser contacts your application route, the storage endpoint, and the completion API. If your application route is on another origin, allow your frontend to call it through CORS.

For your storage, allow the page's origin, PUT requests, and Content-Type. Expose the storage response's ETag header for multipart uploads. Without it, the component cannot complete the part list.

Expose Retry-After too if you want storage retry delays to be readable. Add https://chunkify.dev to the allowed origins if you also upload through the Chunkify dashboard.

Chunkify handles CORS for its completion endpoint. Your bucket's rules are separate. See Configure CORS for provider examples.

If your page has a Content Security Policy, allow https://api.chunkify.dev and your storage endpoint in connect-src.

Component options

Session objects and functions cannot be passed as HTML attributes. Assign upload as a JavaScript property or React prop. Chunkify's plan limits apply independently of the component's file size check.