Vocalise Integration - Capture SDK Documentation

Overview

Hay Festival 2025 - Vocalise Booth Scenario

This API documentation covers the integration between Vocalise and Numbers Protocol for the Hay Festival 2025 voice cloning experience:

Participants visit the Vocalise booth and record their voice
Vocalise AI generates videos using the participant's voice
Participants can choose to download their AI-generated video through a QR code
When downloaded, the video is processed through Numbers Protocol to:

Register the video with digital provenance
Add C2PA watermarking indicating AI generation
Provide download link to the participant

If not downloaded, the video is automatically deleted

Process Flow

flowchart TD A(Participant records voice at Vocalise booth) --> B(AI generates videos) B --> C(Display QR code for video download) C --> D{Participant scans QR?} D -- Yes --> E(Call to Capture API to process video) D -- No --> F(Video deleted from Vocalise server) E --> G(Capture registration) G --> H[C2PA injection] H --> I(Provide download link to participant) I --> J[Optional: Share video to LinkedIn and tag Numbers Protocol & Vocalise]

Quick Start

To use the Vocalise API, you'll need:

A Capture Token (Get your token here)
Video file to process
Preview image (optional)

API Endpoints

POST /api/v3/assets/

1. Register Asset

Reference: Initial Asset Registration Documentation

Parameters

Name	Type	Description	Required
asset_file	File	The video file to be registered	Required
image_file	File	Preview image for the video (e.g., thumbnail)	Optional
headline	String	Title for the video file	Optional
caption	String	Description for the video file	Optional
digital_source_type	String	Set to "digitalUpload" for Vocalise videos	Required
tag	String	Event-specific tag (e.g., "vocalise@hay2025")	Optional
nit_commit_custom	JSON	AI generation and license metadata including: generatedBy: Specify the AI model used to generate this content (e.g., "Midjourney", "DALL-E", or other AI models) miningPreference: Control whether the data can be used for AI training: "aiTrainingWithAuthorship": Allow data to be used for AI training while maintaining authorship "notAllowed": Prevent data from being used in AI training license: License used for the asset and document URL, for example: Creative Commons license Reference: Numbers Protocol AssetTree Documentation	Optional
signed_metadata	JSON	File verification data including: proof_hash: SHA-256 hash of the file asset_mime_type: MIME type of the file	Required
meta	JSON	Additional metadata that stores version information and GPS coordinates: proof: Object containing hash and MIME type hash: SHA-256 hash of the file mimeType: MIME type of the file information: Array of metadata objects provider: Source of the information name: Key name of the metadata value: Value of the metadata Example: { "proof": { "hash": "SHA256_HASH_OF_FILE", "mimeType": "MIME type of the file" }, "information": [ { "provider": "Capture API", "name": "version", "value": "v3" }, { "provider": "InfoSnapshot", "name": "Current GPS Latitude", "value": "51.9580" }, { "provider": "InfoSnapshot", "name": "Current GPS Longitude", "value": "-3.2030" } ] }	Optional

Complete Request Example

curl -X POST "https://api.numbersprotocol.io/api/v3/assets/" \
-H "Authorization: token YOUR_CAPTURE_TOKEN" \
-H "Accept: application/json" \
-F "asset_file=@video.mp4" \
-F "image_file=@preview.png" \
-F "headline=Your File Headline" \
-F "caption=Your File Caption" \
-F "digital_source_type=digitalUpload" \
-F "tag=vocalise@hay2025" \
-F "nit_commit_custom={
    \"generatedBy\":\"AI model\",
    \"miningPreference\":\"aiTrainingWithAuthorship\",
    \"license\":{
        \"name\":\"CC-BY-NC-SA-4.0\",
        \"document\":\"https://creativecommons.org/licenses/by-nc-sa/4.0/\"
    }
}" \
-F "signed_metadata={
    \"proof_hash\":\"SHA256_HASH_OF_FILE\",
    \"asset_mime_type\":\"video/mp4\"
}" \
-F "meta={
    \"proof\":{
        \"hash\":\"SHA256_HASH_OF_FIL\",
        \"mimeType\":\"MIME type of the file\"
    },
    \"information\":[
        {
            \"provider\":\"Capture API\",
            \"name\":\"version\",
            \"value\":\"v3\"
        },
        {
            \"provider\":\"InfoSnapshot\",
            \"name\":\"Current GPS Latitude\",
            \"value\":\"51.9580\"
        },
        {
            \"provider\":\"InfoSnapshot\",
            \"name\":\"Current GPS Longitude\",
            \"value\":\"-3.2030\"
        }
    ]
}"

Response Example

{
    "id": "bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq",
    "asset_file_name": "video.mp4",
    "asset_file_mime_type": "video/mp4",
    "caption": "Your File Caption",
    "headline": "Your File Headline",
    "tag": "vocalise@hay2025"
}

POST /api/v3/assets/{ASSET_ID}/c2pa/

2. Download C2PA

Get the C2PA-injected version of your video.

Reference: Download C2PA injection files

Headers

Name	Type	Description	Required
Authorization	String	Your Capture token in format: "token YOUR_CAPTURE_TOKEN"	Required
Content-Type	String	Set to "application/json"	Required

Path Parameters

Name	Type	Description	Required
ASSET_ID	String	The ID received from asset registration	Required

Complete Request Example

curl -X POST "https://api.numbersprotocol.io/api/v3/assets/{ASSET_ID}/c2pa/" \
-H "Content-Type: application/json" \
-H "Authorization: token YOUR_CAPTURE_TOKEN"

Response Example

{
    "url": "https://ipfs-pin.numbersprotocol.io/ipfs/bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq",
    "cid": "bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq"
}

DELETE /api/v3/assets/{ASSET_ID}/

3. Delete Asset (Optional)

Remove an asset in Numbers database. If an asset is removed, all information stored on Numbers service will be deleted. However, the metadata register on Numbers blockchain will still exist.

Note: This API is an optional one. Since one asset can only be registered on Numbers once, if there is a test asset that has a need to be used multiple times, can use this API to delete the record on Numbers backend and registered again.

Headers

Name	Type	Description	Required
Authorization	String	Your Capture token in format: "token YOUR_CAPTURE_TOKEN"	Required

Path Parameters

Name	Type	Description	Required
ASSET_ID	String	The ID of the asset to delete	Required

Complete Request Example

curl -X DELETE "https://api.numbersprotocol.io/api/v3/assets/{ASSET_ID}/" \
-H "Authorization: token YOUR_CAPTURE_TOKEN"

Response Example

HTTP 204 No Content

GET /api/v3/assets/

4. Query User's Assets (Optional)

List the assets that the user has permission to view.

Reference: Query User's Assets

Headers

Name	Type	Description
Authorization	String	Your Capture token in format: "token YOUR_CAPTURE_TOKEN"

Query Parameters

Name	Type	Description
id	String	Unique ID of the asset.
cid	String	The Nid of the asset.
caption	String	The caption of the asset.
headline	String	The headline of the asset.
tag	String	Comma-separated tags to filter assets (e.g., photo, art).
public_access	Boolean	Whether the asset is publicly accessible.
owner	String	Email of the asset's current owner.
asset_file_name	String	The file name of the asset.
verification_result	String	The verification result of the asset.
integrity_verification_hash	String	The integrity verification hash of the asset.
proof_hash	String	The proof hash tag of the asset.
is_original_owner	Boolean	Whether the asset's current owner is the same as its creator.
limit	Integer	Number of results to return per page.
offset	Integer	The initial index from which to return the results.
uploaded_at_start	String	Filter assets uploaded on or after this date and time.
uploaded_at_end	String	Filter assets uploaded on or before this date and time.
order_by	String	Value: "source_transaction" Change default ordering field.

Complete Request Example

curl -s -X GET 'https://api.numbersprotocol.io/api/v3/assets/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN"

Request with Specific Condition Example

curl -s -X GET 'https://api.numbersprotocol.io/api/v3/assets/?uploaded_at_end=2025-04-30T23:59:59Z' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN"

Response Example

{
    "count": 1,
    "results": [
        {
            "id": "bafybeidixgs2qynnu2zfydcdew5n7d5mw24bnlss6ryxwmw4c2pghxxcxu",
            "cid": "bafybeidixgs2qynnu2zfydcdew5n7d5mw24bnlss6ryxwmw4c2pghxxcxu",
            "asset_file_name": "example.mp4",
            "asset_file_size": 1488753,
            "asset_file_mime_type": "video/mp4",
            "caption": "This is an example",
            "uploaded_at": "2025-04-28T08:52:51.834606Z",
            "owner": "demo@numbersprotocol.io"
        }
    ]
}

Preliminary Experiment

API Processing Time Analysis

Based on preliminary testing, here are the observed processing times for different file sizes:

File Size	Registration API	C2PA Generation API
7M ~ 9M	15 - 25 seconds	6 - 8 seconds
~15M	17 - 36 seconds	8 - 17 seconds

Note: Processing times may vary depending on network conditions and server load. Please account for these processing times when implementing your integration workflow.

References

Authentication & Setup

About Capture
Overview of Capture platform and its capabilities
Get your Capture Token
Learn how to obtain and manage your Capture authentication token

API Documentation

Capture SDK Documentation
Complete SDK documentation and integration guides
Initial Asset Registration
Detailed guide for registering assets with Numbers Protocol
Query User's Assets
Query assets that the user has permission to view
Download C2PA injection files
Guide to C2PA file generation and supported file types
Numbers Protocol AssetTree
Learn about AssetTree structure and metadata format

Additional Resources

Capture FAQ
Frequently asked questions about Capture platform