Create Captures (Asset Registration)

Before Starting
There are three major methods for turning your digital media files into Captures, registering them as Web3 assets, and accessing the Capture ecosystem. These methods include:
1.Using the Capture Cam
2.Using the Capture Dashboard
3.Registering with the Capture API
This page will primarily focus on the third method, registration with the API.
Register Captures
Registering assets via API is a simple way to create Captures. You will need to acquire your Capture Token before uploading the file. If you do not already have a Capture Token yet, please follow the instruction provided to create one.
The API key is optional. If you possess an API key, it's advisable to include it in the header as it helps in recording the name of the service where the asset was registered.
The Capture API is a pay-as-you-go system, which means you only pay for the API calls you make. This is a cost-effective way to use the API and it allows you to control your expenses. Make sure to top up and ensure sufficient funds in your wallet in the form of Credits or NUM to cover the cost. Payment for services is processed using NUM; if you want to know how much it costs in USD, you can check CoinGecko or CoinMarketCap.  
post
https://api.numbersprotocol.io/api/v3/assets/
Register asset
Example
Response
curl -s -X POST 'https://api.numbersprotocol.io/api/v3/assets/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'asset_file=@/tmp/demo.jpg' \
     -F 'meta={
        "proof": {
            "hash": "",
            "mimeType": "",
            "timestamp": ""
        },
        "information": [
            {
                "provider": "Capture API",
                "name": "version",
                "value": "v3"
            }
        ]
     }' \
     -F 'caption=This is an example.'
{
    "id": "bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq",
    "asset_file_name": "demo.jpg",
    "asset_file_mime_type": "image/jpeg",
    "caption": "This is an example.",
}
Please note that proof session is a required part of your metadata. The hash, mimeType, and timestamp fields may be left empty, as the Capture backend will automatically calculate these values for you, as shown in the example above. 
However, the more information you provide, the more trustworthy your assets are, which also make them more "decentralized". The example of meta can be found here.
It's preferable to provide an image file when the asset file is not an image.

For more information on how this registration API works, please refer to the API documentation.
Adding Signatures
In the Capture system, users are able to sign metadata prior to uploading it, thus ensuring the metadata's integrity on the blockchain. signature is the result after signing the metadata with the private key.
To ensure the integrity of your data, it is recommended to sign both the media file and the metadata file before uploading. The signature can be included in the request by using the signature field. For example, if you use AndroidOpenSSL to create the signature, it can be attached using the following command:
curl -s -X POST 'https://api.numbersprotocol.io/api/v3/assets/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'asset_file=@/tmp/demo.jpg' \
     -F 'signature=[{
        "proofHash": "78b67e15077577a9b25393f13bfccde3f94f990cf2a7bb0584a51f09196abbbf",
        "provider": "AndroidOpenSSL",
        "signature": "3046022100b96babf7fb1a374792ce47cebdf0b5a40166352a4e8aed2d8e84a04699898c72022100ec0646e318a0701f794fd0a3dc28da41ff864a1f9156e694b890a1800edd86b0",
        "publicKey": "3059301306072a8648ce3d020106082a8648ce3d030107034200043e4ba565aa9158b9aeafc1bb4a970bfc7fcdcc398c35bb525aedd37bbf459dbd30868b909ec6b78f7904474c225e02f45c2384b0f4ece0d68e2c3c84fce04686"
}]' \
     -F 'meta={
        "proof": {
            "hash": "",
            "mimeType": "",
            "timestamp": ""
        },
        "information": [
            {
                "provider": "Capture API",
                "name": "version",
                "value": "v3"
            }
        ]
     }' \
     -F 'caption=This is an example.'
While the use of signatures is not mandatory, it is highly recommended as it helps to improve the integrity of your data. 
You may also submit the signed_metadata in the API call so that the verification can proceed in the future. For example, if signed_metadata is submitted, the public key (address) can be verified by recovering signed_metadata with the signature provided.
curl -s -X POST 'https://api.numbersprotocol.io/api/v3/assets/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'asset_file=@/tmp/demo.jpg' \
     -F 'signed_metadata={"api_version": "v3"}' \
     -F 'signature=[{
        "proofHash": "78b67e15077577a9b25393f13bfccde3f94f990cf2a7bb0584a51f09196abbbf",
        "provider": "Web3",
        "signature": "0x75f92194df339799748ad8bd12ad4b45ad7b6590431b67900c3b8df21764892b58cbcafb743253e5f70a7965e3706f3d556a056a0089cb164fa2b0fa5cf37ad91c",
        "publicKey": "0xbAbaB9E7790202A1a4d171E44767A531C25e200C"
}]' \
     -F 'meta={
        "proof": {
            "hash": "",
            "mimeType": "",
            "timestamp": ""
        },
        "information": [
            {
                "provider": "Capture API",
                "name": "version",
                "value": "v3"
            }
        ]
     }' \
     -F 'caption=This is an example.'
Additional Capture Information
Additional information in Capture is important because it helps to build trust and transparency in the digital media assets that are created and stored on the decentralized web. Having detailed information about an asset, such as its creation date, location, and owner, is crucial for establishing its authenticity and provenance. More verifiable information, more provenance of your Captures.
Adding information to a Capture is straightforward, one just needs to extend the information blocks during the asset registration. Information blocks can be defined as follows:
{
     "provider": "InfoSnapshot",
     "name": "Current GPS Latitude",
     "value": 25.049190
},
The provider field refers to the source of the information block, while the name field represents the name of the information block. The value to be registered should be placed in the value field. This allows for clear and organized storage of information about the Capture.
The following shows some pre-defined information blocks:
Provider
Name
Sample Value
InfoSnapshot
creationGPSAddress
No. 299, Section 4, Bade Road, Songshan District Taipei City
InfoSnapshot
Timestamp
2021-04-23T02:30:00.279Z
InfoSnapshot
creationGPSLatitude
25.049190
InfoSnapshot
creationGPSLongitude
121.566440
InfoSnapshot
Device Build Tags
android
InfoSnapshot
GPSVerticalAccuracy
8.0
Exif
GPSAltitude
-4.617279052734375
Exif
GPSBearing
212.94905
Exif
GPSverticalAccuracyMeters
8.0
Exif
GPSLongitude
121,31,50.861E
Exif
GPSLatitude
25,2,42.842N
Android
Manufacturer
Samsung
Android
DeviceName
Samsung Galaxy Fold 4
Sensor
Accelerometer
SensorData(accuracy=3.0, value=[-2.2584498, 5.544669, 7.7695217])
Sensor
GameRotationVector
SensorData(accuracy=3.0, value=[0.28894028, 0.089926116, -0.077565834, 0.94995135])
Sensor
Gravity
SensorData(accuracy=NO_UPDATE_RECEIVED_DURING_SNAP, value=[-2.1173487, 5.2436786, 8.011802])
Sensor
Gyroscope
SensorData(accuracy=3.0, value=[0.0090546375, 0.0026631376, 0.011718297])
PGP
Public Key
----BEGIN PGP PUBLIC KEY BLOCK-----Version: BCPG v@RELEASE_NAME@mQINBF5emRQBEAC0YLMyonrxA==YeTD-----END PGP PUBLIC KEY BLOCK-----
IPFS
Nid
bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq
Import Assets
The importing API endpoint is used for importing NFTs.
post
https://api.numbersprotocol.io/api/v3
/assets/import/
Import asset
Cost: 0.1 NUM per API call + Gas (~0.004 NUM per transaction)
Parameters
Header
Authorization*
String
Example
token YOUR_CAPTURE_TOKEN
X-Api-Key
String
YOUR_API_KEY
Content-Type
String
multipart/form-data
Body
nft*
Object
The imported NFT. 
nft_chain_id
nft_contract_address
nft_token_id
image_file
Object
The image file. Its size should not exceed 100 MB.
meta
String
JSON string containing the metadata of the asset_file provided by user.
signed_metadata
String
The signed metadata which could be verified with signature.
signature
String
JSON string containing a list of signatures which were used to sign the data or metadata.
Responses
201: Created
Import successfully
401: Unauthorized
500: Internal Server Error
​
Example: import an NFT where the owner is the asset wallet
Example: import an NFT where the owner is not the asset wallet 
Response
curl -s -X POST 'https://api.numbersprotocol.io/api/v3/assets/import/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
         "nft": {
             "nft_chain_id": 1,
             "nft_contract_address": "0xfDD0642479Bb1E219945E7a44B882AfaB8BaF68B",
             "nft_token_id": "1"
         },
         "meta": "{\"proof\": {\"hash\": \"\",\"mimeType\":\"\",\"timestamp\": \"\"},\"information\": [{\"provider\": \"Capture API\",\"name\": \"version\",\"value\": \"v3\"}]}"
     }'
curl -s -X POST 'https://api.numbersprotocol.io/api/v3/assets/import/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
         "nft": {
             "nft_chain_id": 1,
             "nft_contract_address": "0xfDD0642479Bb1E219945E7a44B882AfaB8BaF68B",
             "nft_token_id": "1"
         },
         "meta": "{\"proof\": {\"hash\": \"\",\"mimeType\":\"\",\"timestamp\": \"\"},\"information\": [{\"provider\": \"Capture API\",\"name\": \"version\",\"value\": \"v3\"}]}",
         "signed_metadata": "{\"api_version\": \"v3\"}",
         "signature": "[{\"proofHash\": \"78b67e15077577a9b25393f13bfccde3f94f990cf2a7bb0584a51f09196abbbf\",\"provider\": \"Web3\",\"signature\": \"0x75f92194df339799748ad8bd12ad4b45ad7b6590431b67900c3b8df21764892b58cbcafb743253e5f70a7965e3706f3d556a056a0089cb164fa2b0fa5cf37ad91c\",\"publicKey\": \"0xbAbaB9E7790202A1a4d171E44767A531C25e200C\"}]"
     }'
{
    "id": "bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq",
    "asset_file_name": "imported.jpg",
    "asset_file_mime_type": "image/jpeg",
    "caption": "This is an example.",
    "nft_token_id": "1",
    "nft_chain_id": 1,
    "nft_contract_address": "0xfDD0642479Bb1E219945E7a44B882AfaB8BaF68B"
}
​
Example: Import an NFT with an associated image
Response
curl -s -X POST 'https://api.numbersprotocol.io/api/v3/assets/import/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'nft.nft_chain_id=1' \
     -F 'nft.nft_contract_address=0xfDD0642479Bb1E219945E7a44B882AfaB8BaF68B' \
     -F 'nft.nft_token_id=2' \
     -F 'image_file=@/tmp/demo.jpg' \
     -F 'signed_metadata={"api_version": "v3"}' \
     -F 'signature=[{
        "proofHash": "78b67e15077577a9b25393f13bfccde3f94f990cf2a7bb0584a51f09196abbbf",
        "provider": "Web3",
        "signature": "0x75f92194df339799748ad8bd12ad4b45ad7b6590431b67900c3b8df21764892b58cbcafb743253e5f70a7965e3706f3d556a056a0089cb164fa2b0fa5cf37ad91c",
        "publicKey": "0xbAbaB9E7790202A1a4d171E44767A531C25e200C"
}]' \
     -F 'meta={
        "proof": {
            "hash": "",
            "mimeType": "",
            "timestamp": ""
        },
        "information": [
            {
                "provider": "Capture API",
                "name": "version",
                "value": "v3"
            }
        ]
     }'
{
    "id": "bafybeiagc3fjrdrrookzkbrtdnfuulpfmeqej3bqc6wpmuttsclykuidt4",
    "asset_file_name": "imported.mp4",
    "asset_file_mime_type": "video/mp4",
    "image_file_mime_type": "image/jpeg",
    "caption": "This is an example.",
    "nft_token_id": "2",
    "nft_chain_id": 1,
    "nft_contract_address": "0xfDD0642479Bb1E219945E7a44B882AfaB8BaF68B"
}
The nft is required to import an NFT from Numbers Search Engine​.​
If the NFT owner is not the user's asset wallet, the signed_metadata and signature are also necessary. These will be used to validate the address that signed the signed_metadata as the NFT owner.
It is recommended to provide an image_file when the NFT's image is not in image file format.
If the owner of the imported NFT is the user's asset wallet, the user can perform any NFT operation, including forcing a re-mint of an asset, exporting an asset, creating a transaction, creating an asset-origin product, creating an asset-clone product, or creating pack products from a series. However, if the owner is not the user's asset wallet, the user can only mint new NFTs (create child assets), which includes creating an asset-clone product, and creating pack products from a series.
Query Assets
The following API endpoint can be used to query asset information.
get
https://api.numbersprotocol.io/api/v3/assets/
Query registered assets information
Example: query all assets
Response
curl -s -X GET 'https://api.numbersprotocol.io/api/v3/assets/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN"
[
    {
        "id": "bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq",
        "asset_file_name": "demo.jpg",
        "asset_file_mime_type": "image/jpeg",
        "caption": "This is an example."
    }
]
Example: query one asset
Response
curl -s -X GET 'https://api.numbersprotocol.io/api/v3/assets/YOUR_ASSET_NID/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN"
{
    "id": "bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq",
    "asset_file_name": "demo.jpg",
    "asset_file_mime_type": "image/jpeg",
    "caption": "This is an example."
}
Full list of Capture APIs
See here for the full API list.

Provider	Name	Sample Value
InfoSnapshot	creationGPSAddress	No. 299, Section 4, Bade Road, Songshan District Taipei City
InfoSnapshot	Timestamp	2021-04-23T02:30:00.279Z
InfoSnapshot	creationGPSLatitude	25.049190
InfoSnapshot	creationGPSLongitude	121.566440
InfoSnapshot	Device Build Tags	android
InfoSnapshot	GPSVerticalAccuracy	8.0
Exif	GPSAltitude	-4.617279052734375
Exif	GPSBearing	212.94905
Exif	GPSverticalAccuracyMeters	8.0
Exif	GPSLongitude	121,31,50.861E
Exif	GPSLatitude	25,2,42.842N
Android	Manufacturer	Samsung
Android	DeviceName	Samsung Galaxy Fold 4
Sensor	Accelerometer	SensorData(accuracy=3.0, value=[-2.2584498, 5.544669, 7.7695217])
Sensor	GameRotationVector	SensorData(accuracy=3.0, value=[0.28894028, 0.089926116, -0.077565834, 0.94995135])
Sensor	Gravity	SensorData(accuracy=NO_UPDATE_RECEIVED_DURING_SNAP, value=[-2.1173487, 5.2436786, 8.011802])
Sensor	Gyroscope	SensorData(accuracy=3.0, value=[0.0090546375, 0.0026631376, 0.011718297])
PGP	Public Key	----BEGIN PGP PUBLIC KEY BLOCK-----Version: BCPG v@RELEASE_NAME@mQINBF5emRQBEAC0YLMyonrxA==YeTD-----END PGP PUBLIC KEY BLOCK-----
IPFS	Nid	bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq

Top Up

Capture Cam Feature List

Last modified 10d ago