Link video assets, uploads, sources, and jobs to your application records with custom metadata.
Use metadata to associate Chunkify resources with records in your application. Add your own video ID, an uploader ID, or labels to video assets, Uploads, Sources, and Jobs.
For example, a customer uploads a video to your application. Your database identifies the video as video-123 and the uploader as user_demo. Add these IDs as VideoID and uploaded_by in Chunkify metadata so you can find the video in webhook notifications and list requests.
Keep the resource's Chunkify ID alongside your own ID so you can retrieve or manage it directly.
Metadata is an optional flat map of string keys and string values. You choose the key names, and they are case-sensitive. Each resource's metadata can contain up to 2048 bytes of encoded JSON, including keys and JSON formatting.
Add metadata to a resource
Video assets
Pass metadata when creating a video asset from an existing Source. This example links the video asset to your application's video-123 record and its uploader, user_demo:
Jobs also accept metadata at creation. Use a shared group value for Jobs that belong to the same export task. You can then filter by that value to retrieve the task's Jobs:
Filter list requests with key:value conditions. Matching is exact, and every supplied condition must match. Keys and values used in these filters must be non-empty and cannot contain a colon.
For example, use uploaded_by:user_demo to find a customer's videos, or group:test_jobs to find the Jobs labeled above.
The examples below display the first page of each paginated result.
Video asset filters
Video asset lists accept a flat array of conditions. This finds videos uploaded by user_demo with the application ID video-123:
Upload, Source, and Job lists use nested arrays in their SDK parameters, with one key:value condition per inner array. These examples filter Jobs by group and Sources by uploaded_by:
Add metadata when creating an Upload session. After the upload completes, Chunkify copies it to the Source. If you set create_asset: true, it also copies the same metadata to the video asset.
This example includes your application's video and uploader IDs, uses your Project's default storage for the original, and requests a video asset after completion:
Use the selected file's exact size in place of 104857600. For Chunkify temporary storage, omit storage. See Video upload for transferring and completing the file, or use Chunkify Uploader in the browser.
Each resource keeps its own metadata copy. Updating the video asset's metadata later does not change the Source or Upload.
Update video asset metadata
A video asset's metadata update replaces the entire map. Include every key you want to keep. This example preserves the video and uploader IDs and adds a collection label:
Omit metadata to leave it unchanged. Send an empty JSON object, metadata: {}, to clear it. null is not accepted. See Update a video asset for the request fields.
Use metadata in output paths
For video assets stored in your storage, an output path template can reference metadata. With videos/{metadata.VideoID} and VideoID set to video-123, the output folder is videos/video-123/, relative to the storage's output prefix.
Include every referenced key with a non-empty value at creation. When an Upload requests a video asset, provide those values in the Upload metadata. Keys are case-sensitive.
Changing metadata later does not move existing files or change their paths. See Output paths for templates, prefixes, and destination rules.
Read metadata from events
Resource metadata is included in webhook payloads. For example, asset.playback_ready includes it in data.asset.metadata; upload.completed includes it in data.upload.metadata and data.source.metadata.
For the video-123 example, your server verifies the asset.playback_ready webhook and reads data.asset.metadata.VideoID. It uses that ID to find the video in your database, save its playback URL, and mark it as playable. Your application can then show the video to the customer who uploaded it.
See Webhooks for setup and signature verification, and Events for the event list.
# Metadata
> Link video assets, uploads, sources, and jobs to your application records with custom metadata.
Use metadata to associate Chunkify resources with records in your application. Add your own video ID, an uploader ID, or labels to video assets, Uploads, Sources, and Jobs.
For example, a customer uploads a video to your application. Your database identifies the video as `video-123` and the uploader as `user_demo`. Add these IDs as `VideoID` and `uploaded_by` in Chunkify metadata so you can find the video in webhook notifications and list requests.
Keep the resource's Chunkify ID alongside your own ID so you can retrieve or manage it directly.
Metadata is an optional flat map of string keys and string values. You choose the key names, and they are case-sensitive. Each resource's metadata can contain up to 2048 bytes of encoded JSON, including keys and JSON formatting.
<!-- SDK publication check: Asset create, list, and update methods and Upload creation fields follow api/openapi.json and existing SDK conventions. Verify them in every supported SDK after generation, including []string Asset filters versus [][]string filters for other resources. -->
## Add metadata to a resource
### Video assets
Pass `metadata` when creating a video asset from an existing Source. This example links the video asset to your application's `video-123` record and its uploader, `user_demo`:
<codegroup>
<codeblock lang="Typescript">
```typescript
import Chunkify from '@chunkify/chunkify';
const client = new Chunkify({
projectAccessToken: 'My Project Access Token',
});
const asset = await client.assets.create({
source_id: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
metadata: {
VideoID: 'video-123',
uploaded_by: 'user_demo',
},
});
console.log(asset.id);
```
</codeblock>
<codeblock lang="Python">
```python
from chunkify import Chunkify
client = Chunkify(
project_access_token="My Project Access Token",
)
asset = client.assets.create(
source_id="src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
metadata={
"VideoID": "video-123",
"uploaded_by": "user_demo",
},
)
print(asset.id)
```
</codeblock>
<codeblock lang="PHP">
```php
<?php
use Chunkify\Client;
require_once __DIR__ . '/vendor/autoload.php';
$client = new Client(
projectAccessToken: 'My Project Access Token',
);
$asset = $client->assets->create(
sourceID: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
metadata: [
'VideoID' => 'video-123',
'uploaded_by' => 'user_demo',
],
);
var_dump($asset->id);
```
</codeblock>
<codeblock lang="Go">
```go
package main
import (
"context"
"fmt"
"github.com/chunkifydev/chunkify-go"
"github.com/chunkifydev/chunkify-go/option"
)
func main() {
client := chunkify.NewClient(
option.WithProjectAccessToken("My Project Access Token"),
)
asset, err := client.Assets.New(
context.Background(),
chunkify.AssetNewParams{
SourceID: "src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
Metadata: map[string]string{
"VideoID": "video-123",
"uploaded_by": "user_demo",
},
},
)
if err != nil {
panic(err)
}
fmt.Println(asset.ID)
}
```
</codeblock>
</codegroup>
### Transcoding jobs
Jobs also accept metadata at creation. Use a shared `group` value for Jobs that belong to the same export task. You can then filter by that value to retrieve the task's Jobs:
<codegroup>
<codeblock lang="Typescript">
```typescript
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',
height: 1080,
},
metadata: {
group: 'test_jobs',
},
});
console.log(job.id);
```
</codeblock>
<codeblock lang="Python">
```python
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",
"height": 1080,
},
metadata={
"group": "test_jobs",
},
)
print(job.id)
```
</codeblock>
<codeblock lang="PHP">
```php
<?php
use Chunkify\Client;
require_once __DIR__ . '/vendor/autoload.php';
$client = new Client(
projectAccessToken: 'My Project Access Token',
);
$job = $client->jobs->create(
sourceID: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
format: [
'id' => 'mp4_h264',
'height' => 1080,
],
metadata: [
'group' => 'test_jobs',
],
);
var_dump($job->id);
```
</codeblock>
<codeblock lang="Go">
```go
package main
import (
"context"
"fmt"
"github.com/chunkifydev/chunkify-go"
"github.com/chunkifydev/chunkify-go/option"
)
func main() {
client := chunkify.NewClient(
option.WithProjectAccessToken("My Project Access Token"),
)
job, err := client.Jobs.New(
context.Background(),
chunkify.JobNewParams{
SourceID: "src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
Format: chunkify.JobNewParamsFormatUnion{
OfMP4H264: &chunkify.MP4H264Param{
Height: chunkify.Int(1080),
},
},
Metadata: map[string]string{
"group": "test_jobs",
},
},
)
if err != nil {
panic(err)
}
fmt.Println(job.ID)
}
```
</codeblock>
</codegroup>
## Filter resources by metadata
Filter list requests with `key:value` conditions. Matching is exact, and every supplied condition must match. Keys and values used in these filters must be non-empty and cannot contain a colon.
For example, use `uploaded_by:user_demo` to find a customer's videos, or `group:test_jobs` to find the Jobs labeled above.
The examples below display the first page of each paginated result.
<a id="key-value-filtering"></a>
### Video asset filters
Video asset lists accept a flat array of conditions. This finds videos uploaded by `user_demo` with the application ID `video-123`:
<codegroup>
<codeblock lang="Typescript">
```typescript
import Chunkify from '@chunkify/chunkify';
const client = new Chunkify({
projectAccessToken: 'My Project Access Token',
});
const assets = await client.assets.list({
metadata: ['VideoID:video-123', 'uploaded_by:user_demo'],
});
console.log(assets.data);
```
</codeblock>
<codeblock lang="Python">
```python
from chunkify import Chunkify
client = Chunkify(
project_access_token="My Project Access Token",
)
assets = client.assets.list(
metadata=["VideoID:video-123", "uploaded_by:user_demo"],
)
print(assets.data)
```
</codeblock>
<codeblock lang="PHP">
```php
<?php
use Chunkify\Client;
require_once __DIR__ . '/vendor/autoload.php';
$client = new Client(
projectAccessToken: 'My Project Access Token',
);
$assets = $client->assets->list(
metadata: ['VideoID:video-123', 'uploaded_by:user_demo'],
);
print_r($assets->getItems());
```
</codeblock>
<codeblock lang="Go">
```go
package main
import (
"context"
"fmt"
"github.com/chunkifydev/chunkify-go"
"github.com/chunkifydev/chunkify-go/option"
)
func main() {
client := chunkify.NewClient(
option.WithProjectAccessToken("My Project Access Token"),
)
assets, err := client.Assets.List(
context.Background(),
chunkify.AssetListParams{
Metadata: []string{
"VideoID:video-123",
"uploaded_by:user_demo",
},
},
)
if err != nil {
panic(err)
}
fmt.Println(assets.Data)
}
```
</codeblock>
</codegroup>
### Other resource filters
Upload, Source, and Job lists use nested arrays in their SDK parameters, with one `key:value` condition per inner array. These examples filter Jobs by `group` and Sources by `uploaded_by`:
<codegroup>
<codeblock lang="Typescript">
```typescript
import Chunkify from '@chunkify/chunkify';
const client = new Chunkify({
projectAccessToken: 'My Project Access Token',
});
const jobs = await client.jobs.list({
metadata: [['group:test_jobs']],
});
const sources = await client.sources.list({
metadata: [['uploaded_by:user_demo']],
});
console.log(jobs.data);
console.log(sources.data);
```
</codeblock>
<codeblock lang="Python">
```python
from chunkify import Chunkify
client = Chunkify(
project_access_token="My Project Access Token",
)
jobs = client.jobs.list(
metadata=[["group:test_jobs"]],
)
sources = client.sources.list(
metadata=[["uploaded_by:user_demo"]],
)
print(jobs.data)
print(sources.data)
```
</codeblock>
<codeblock lang="PHP">
```php
<?php
use Chunkify\Client;
require_once __DIR__ . '/vendor/autoload.php';
$client = new Client(
projectAccessToken: 'My Project Access Token',
);
$jobs = $client->jobs->list(
metadata: [['group:test_jobs']],
);
$sources = $client->sources->list(
metadata: [['uploaded_by:user_demo']],
);
print_r($jobs->getItems());
print_r($sources->getItems());
```
</codeblock>
<codeblock lang="Go">
```go
package main
import (
"context"
"fmt"
"github.com/chunkifydev/chunkify-go"
"github.com/chunkifydev/chunkify-go/option"
)
func main() {
client := chunkify.NewClient(
option.WithProjectAccessToken("My Project Access Token"),
)
jobs, err := client.Jobs.List(
context.Background(),
chunkify.JobListParams{
Metadata: [][]string{
{"group:test_jobs"},
},
},
)
if err != nil {
panic(err)
}
sources, err := client.Sources.List(
context.Background(),
chunkify.SourceListParams{
Metadata: [][]string{
{"uploaded_by:user_demo"},
},
},
)
if err != nil {
panic(err)
}
fmt.Println(jobs.Data)
fmt.Println(sources.Data)
}
```
</codeblock>
</codegroup>
<a id="metadata-on-uploads-and-sources"></a>
## Metadata across resources
Add metadata when creating an Upload session. After the upload completes, Chunkify copies it to the Source. If you set `create_asset: true`, it also copies the same metadata to the video asset.
This example includes your application's video and uploader IDs, uses your Project's default storage for the original, and requests a video asset after completion:
<codegroup>
<codeblock lang="Typescript">
```typescript
import Chunkify from '@chunkify/chunkify';
const client = new Chunkify({
projectAccessToken: 'My Project Access Token',
});
const upload = await client.uploads.create({
upload_mode: 'auto',
file_size_bytes: 104857600,
create_asset: true,
storage: {
path: 'incoming/video-123.mp4',
},
metadata: {
VideoID: 'video-123',
uploaded_by: 'user_demo',
},
});
console.log(upload.id);
```
</codeblock>
<codeblock lang="Python">
```python
from chunkify import Chunkify
client = Chunkify(
project_access_token="My Project Access Token",
)
upload = client.uploads.create(
upload_mode="auto",
file_size_bytes=104857600,
create_asset=True,
storage={
"path": "incoming/video-123.mp4",
},
metadata={
"VideoID": "video-123",
"uploaded_by": "user_demo",
},
)
print(upload.id)
```
</codeblock>
<codeblock lang="PHP">
```php
<?php
use Chunkify\Client;
require_once __DIR__ . '/vendor/autoload.php';
$client = new Client(
projectAccessToken: 'My Project Access Token',
);
$upload = $client->uploads->create(
uploadMode: 'auto',
fileSizeBytes: 104857600,
createAsset: true,
storage: [
'path' => 'incoming/video-123.mp4',
],
metadata: [
'VideoID' => 'video-123',
'uploaded_by' => 'user_demo',
],
);
var_dump($upload->id);
```
</codeblock>
<codeblock lang="Go">
```go
package main
import (
"context"
"fmt"
"github.com/chunkifydev/chunkify-go"
"github.com/chunkifydev/chunkify-go/option"
)
func main() {
client := chunkify.NewClient(
option.WithProjectAccessToken("My Project Access Token"),
)
upload, err := client.Uploads.New(
context.Background(),
chunkify.UploadNewParams{
UploadMode: chunkify.UploadNewParamsUploadModeAuto,
FileSizeBytes: chunkify.Int(104857600),
CreateAsset: chunkify.Bool(true),
Storage: chunkify.UploadNewParamsStorage{
Path: chunkify.String("incoming/video-123.mp4"),
},
Metadata: map[string]string{
"VideoID": "video-123",
"uploaded_by": "user_demo",
},
},
)
if err != nil {
panic(err)
}
fmt.Println(upload.ID)
}
```
</codeblock>
</codegroup>
Use the selected file's exact size in place of `104857600`. For Chunkify temporary storage, omit `storage`. See [Video upload](/docs/integration/video-upload) for transferring and completing the file, or use [Chunkify Uploader](/docs/integration/uploader) in the browser.
Each resource keeps its own metadata copy. Updating the video asset's metadata later does not change the Source or Upload.
## Update video asset metadata
A video asset's `metadata` update replaces the entire map. Include every key you want to keep. This example preserves the video and uploader IDs and adds a collection label:
<codegroup>
<codeblock lang="Typescript">
```typescript
import Chunkify from '@chunkify/chunkify';
const client = new Chunkify({
projectAccessToken: 'My Project Access Token',
});
await client.assets.update('asset_2G6MJiNz71bHQGNzGwKx5cJwPFS', {
metadata: {
VideoID: 'video-123',
uploaded_by: 'user_demo',
collection: 'training',
},
});
```
</codeblock>
<codeblock lang="Python">
```python
from chunkify import Chunkify
client = Chunkify(
project_access_token="My Project Access Token",
)
client.assets.update(
"asset_2G6MJiNz71bHQGNzGwKx5cJwPFS",
metadata={
"VideoID": "video-123",
"uploaded_by": "user_demo",
"collection": "training",
},
)
```
</codeblock>
<codeblock lang="PHP">
```php
<?php
use Chunkify\Client;
require_once __DIR__ . '/vendor/autoload.php';
$client = new Client(
projectAccessToken: 'My Project Access Token',
);
$client->assets->update(
'asset_2G6MJiNz71bHQGNzGwKx5cJwPFS',
metadata: [
'VideoID' => 'video-123',
'uploaded_by' => 'user_demo',
'collection' => 'training',
],
);
```
</codeblock>
<codeblock lang="Go">
```go
package main
import (
"context"
"github.com/chunkifydev/chunkify-go"
"github.com/chunkifydev/chunkify-go/option"
)
func main() {
client := chunkify.NewClient(
option.WithProjectAccessToken("My Project Access Token"),
)
err := client.Assets.Update(
context.Background(),
"asset_2G6MJiNz71bHQGNzGwKx5cJwPFS",
chunkify.AssetUpdateParams{
Metadata: map[string]string{
"VideoID": "video-123",
"uploaded_by": "user_demo",
"collection": "training",
},
},
)
if err != nil {
panic(err)
}
}
```
</codeblock>
</codegroup>
Omit `metadata` to leave it unchanged. Send an empty JSON object, `metadata: {}`, to clear it. `null` is not accepted. See [Update a video asset](/docs/api-reference/assets/update-an-asset) for the request fields.
## Use metadata in output paths
For video assets stored in your storage, an output path template can reference metadata. With `videos/{metadata.VideoID}` and `VideoID` set to `video-123`, the output folder is `videos/video-123/`, relative to the storage's output prefix.
Include every referenced key with a non-empty value at creation. When an Upload requests a video asset, provide those values in the Upload metadata. Keys are case-sensitive.
Changing metadata later does not move existing files or change their paths. See [Output paths](/docs/video-streaming/storage/output-paths) for templates, prefixes, and destination rules.
## Read metadata from events
Resource metadata is included in webhook payloads. For example, `asset.playback_ready` includes it in `data.asset.metadata`; `upload.completed` includes it in `data.upload.metadata` and `data.source.metadata`.
For the `video-123` example, your server verifies the `asset.playback_ready` webhook and reads `data.asset.metadata.VideoID`. It uses that ID to find the video in your database, save its playback URL, and mark it as playable. Your application can then show the video to the customer who uploaded it.
See [Webhooks](/docs/integration/webhooks) for setup and signature verification, and [Events](/docs/integration/events) for the event list.