FsFiles

List the files and results

GET https://api-v2.acrcloud.com/api/fs-containers/:container_id/files

This endpoint will not show the youtube channels/playlists results.

Path Parameters

Name

Type

Description

container_id

number

The container id

Query Parameters

Name

Type

Description

page

number

The page number

per_page

number

The results number per page

string

Search by name or URI

with_result

number

1:list the files with results. 0:will not list the results (default)

state

String

0:processing 1:Ready (Recognize results from a file.) -1: No results (No results were recognized from the file.) -2,-3: Error

Headers

Name

Type

Description

Authorization

string

Bearer token

{
    "data":[
        {
            "id":"fd0cbc13-bb69-41ed-abbb-1ed6f25c3b02",
            "uid":19,
            "cid":10005,
            "name":"Camilo - Millones (Official Video)",
            "duration":222,
            "uri":"youtube:video:krP539YBF7U",
            "data_type":"youtube",
            "engine":1,
            "count":1,
            "state":1,
            "created_at":"2021-04-08T10:23:29.000000Z",
            "updated_at":"2021-04-23T02:58:04.000000Z",
            "total":1,
            "music_detected":1, //0:Unknown, 1: Music or Music with speech, 2: Others
            "results":{
               "music_speech": [
                    {
                        "start": 0,
                        "end": 222,
                        "label": "m" //m:Music, ms:Music & Speech, s:Speech, o:Others
                    }
                ],
                "music":[
                    {
                        "offset":0,
                        "played_duration":220,
                        "type":"traverse",
                        "result":{
                            "album":{
                                "name":"Mis Manos"
                            },
                            "play_offset_ms":19780,
                            "sample_begin_time_offset_ms":0,
                            "contributors":{
                                "composers":[
                                    "Camilo Echeverry",
                                    "Édgar Barrera"
                                ],
                                "lyricists":[
                                    "Camilo Echeverry",
                                    "Édgar Barrera"
                                ]
                            },
                            "title":"Millones",
                            "result_from":3,
                            "release_date":"2021-03-04",
                            "sample_end_time_offset_ms":9440,
                            "genres":[
                                {
                                    "name":"Latin Pop"
                                }
                            ],
                            "label":"SME - Sony Music Latin",
                            "db_end_time_offset_ms":19300,
                            "score":100,
                            "db_begin_time_offset_ms":9860,
                            "artists":[
                                {
                                    "name":"Camilo"
                                }
                            ],
                            "duration_ms":221000,
                            "external_ids":{
                                "isrc":"USSD12100051",
                                "upc":"886449088867"
                            },
                            "acrid":"300f34d92ec1f3a7397bb2bb9cddf884",
                            "external_metadata":{
                                "spotify":{
                                    "album":{
                                        "name":"Mis Manos"
                                    },
                                    "track":{
                                        "name":"Millones",
                                        "id":"3YAnNBdk0uHyakXXzMbNJq"
                                    },
                                    "artists":[
                                        {
                                            "name":"Camilo"
                                        }
                                    ]
                                },
                                "deezer":{
                                    "album":{
                                        "name":""
                                    },
                                    "track":{
                                        "name":"Millones",
                                        "id":"1260566282"
                                    },
                                    "artists":[
                                        {
                                            "name":"Camilo"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                ]
            }
        },
        {
            "id":"5c2cfaa2-6024-4775-ac24-1aa7b4786c86",
            "uid":19,
            "cid":10005,
            "name":"Lil Tjay - Love Hurts (Feat. Toosii) [Official Video]",
            "duration":247,
            "uri":"youtube:video:V-IDVYH3YjA",
            "data_type":"youtube",
            "engine":1,
            "count":1,
            "state":1,
            "created_at":"2021-04-08T08:26:55.000000Z",
            "updated_at":"2021-04-23T02:58:04.000000Z",
            "total":1,
            "music_detected":1
            "results":{
                "music_speech": [
                    {
                        "start": 0,
                        "end": 247,
                        "label": "m"
                    }
                ],
                "music":[
                    {
                        "offset":14,
                        "played_duration":5,
                        "type":"traverse",
                        "result":{
                            "album":{
                                "name":"my ex called"
                            },
                            "play_offset_ms":6440,
                            "sample_begin_time_offset_ms":4260,
                            "title":"my ex called",
                            "result_from":3,
                            "release_date":"2020-02-21",
                            "sample_end_time_offset_ms":8860,
                            "label":"Thrill$",
                            "db_end_time_offset_ms":4600,
                            "score":100,
                            "db_begin_time_offset_ms":0,
                            "artists":[
                                {
                                    "name":"Thrill$"
                                }
                            ],
                            "duration_ms":168920,
                            "external_ids":{
                                "isrc":"QZJG52083365",
                                "upc":"194923628486"
                            },
                            "acrid":"269e27604f4be4c3167fc3751f5551c3",
                            "external_metadata":{
                                "deezer":{
                                    "album":{
                                        "name":""
                                    },
                                    "track":{
                                        "name":"Havit",
                                        "id":"1098021672"
                                    },
                                    "artists":[
                                        {
                                            "name":"Of_mannyg"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "offset":24,
                        "played_duration":14,
                        "type":"traverse",
                        "result":{
                            "album":{
                                "name":"Lost Files"
                            },
                            "play_offset_ms":5340,
                            "sample_begin_time_offset_ms":4080,
                            "title":"In the Streets",
                            "result_from":1,
                            "release_date":"2020-10-26",
                            "sample_end_time_offset_ms":9260,
                            "label":"Hitta Huncho",
                            "db_end_time_offset_ms":5180,
                            "score":100,
                            "db_begin_time_offset_ms":0,
                            "artists":[
                                {
                                    "name":"Hitta Huncho"
                                }
                            ],
                            "duration_ms":160940,
                            "external_ids":{
                                "isrc":"TCAFE2056515",
                                "upc":"859742903298"
                            },
                            "acrid":"e63ee358a9357a1e181cd8ce858d78fd",
                            "external_metadata":{
                                "deezer":{
                                    "album":{
                                        "name":""
                                    },
                                    "track":{
                                        "name":"In the Streets",
                                        "id":"1131507852"
                                    },
                                    "artists":[
                                        {
                                            "name":"Hitta Huncho"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "offset":30,
                        "played_duration":209,
                        "type":"traverse",
                        "result":{
                            "album":{
                                "name":"Destined 2 Win"
                            },
                            "play_offset_ms":25880,
                            "sample_begin_time_offset_ms":0,
                            "title":"Love Hurts",
                            "result_from":1,
                            "release_date":"2021-04-02",
                            "sample_end_time_offset_ms":8200,
                            "genres":[
                                {
                                    "name":"Hip Hop"
                                }
                            ],
                            "label":"Columbia",
                            "db_end_time_offset_ms":24100,
                            "score":100,
                            "db_begin_time_offset_ms":15900,
                            "artists":[
                                {
                                    "name":"Lil Tjay"
                                }
                            ],
                            "duration_ms":222100,
                            "external_ids":{
                                "isrc":"USSM12101539",
                                "upc":"886449173587"
                            },
                            "acrid":"d981bc8a8a55b06d15d5ea0f4957873c",
                            "external_metadata":{
                                "spotify":{
                                    "album":{
                                        "name":"Destined 2 Win"
                                    },
                                    "track":{
                                        "name":"Love Hurts (feat. Toosii)",
                                        "id":"2ULQtFHTzUK0DqcqWUlXxw"
                                    },
                                    "artists":[
                                        {
                                            "name":"Lil Tjay"
                                        },
                                        {
                                            "name":"Toosii"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                ]
            }
        }
    ],
    "links":{
        "first":"https://ap-api-v2.acrcloud.com/api/fs-containers/10005/files?page=1",
        "last":"https://ap-api-v2.acrcloud.com/api/fs-containers/10005/files?page=1",
        "prev":null,
        "next":null
    },
    "meta":{
        "current_page":1,
        "from":1,
        "last_page":1,
        "path":"https://ap-api-v2.acrcloud.com/api/fs-containers/10005/files",
        "per_page":"20",
        "to":2,
        "total":2
    }
}

curl --location --request GET 'https://api-v2.acrcloud.com/api/fs-containers/:your_container_id/files?page=1&per_page=20' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YourAccessToken'

import requests

url = "https://api-v2.acrcloud.com/api/fs-containers/:your_container_id/files?page=1&per_page=20"

payload={}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer token'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response descriptions

Field Name

Type

Description

String

The id of the file

uid

Integer

The id of the acrcloud console account

cid

Integer

The id of the fs container

name

String

The name of the file

duration

Integer

The duration of the audio file

uri

String

The uri of the file. if the data_type is audio/fingerprint format: audio:file_name if the data_type is audio_url format: audio_url:url_path if the data_type is platforms, such as youtube, twitter, tiktok... format: platform:video:platform_id youtube:video:7wtfhZwyrcc

data_type

String

audio: upload the audio file to the container fingerprint: upload the acrcloud fingerprint to the container audio_url: upload the http/https/ftp url to the container platforms: upload the platform url, such as

engine

Integer

What engine was used to recognize this file? 1: audio fingerprint 2: cover song identification 3: audio fingerprint & cover song identification 4: Speech recognition (STT)

count

Integer

This field is temporarily not in use.

state

Integer

Current state of the document: 0:processing 1:Ready (Recognize results from a file.) -1: No results (No results were recognized from the file.) -2,-3: Error

total

Integer

This field is temporarily not in use. The total sub-files does this file contains

results

JSON

{ "music":[], //audio fingerprint music results "cover_songs":[], // cover songs results "custom_files":[], // audio fingerprint custom files matched results "speech":[], //STT results 'music_speech":[] // music/speech detection results. }

created_at

String

The creation time(UTC+0) of the file

updated_at

String

The update time(UTC+0) of the file

Upload a file or platforms web url

POST https://api-v2.acrcloud.com/api/fs-containers/:container_id/files

Path Parameters

Name

Type

Description

container_id*

number

The container id

Headers

Name

Type

Description

Authorization*

string

Bearer token

Request Body

Name

Type

Description

file

object

The audio or fingerprint file, "audio" data_type requires this field.

data_type*

string

audio: Upload an audio file fingerprint: Upload a fingerprint file platforms: platforms url. Currently, supported platforms are Youtube,Twitter, Tiktok, Vimeo, Brightcove...etc. You can post the platform's web url to this endpoint. audio_url: Downloadable audio url.

url

string

If the datatype is platforms or audio_url, you need to add this parameter. For example:

name

String

If you do not pass this parameter, we will use the file path or url path as the file name.

{
    "data": {
        "uid": 19,
        "cid": 10005,
        "name": "886443683402_US4D80623007.lo",
        "duration": 159.56,
        "uri": "audio:886443683402_US4D80623007.lo",
        "data_type": "audio",
        "method": 1,
        "count": 0,
        "state": 0,
        "updated_at": "2021-04-23T07:33:21.000000Z",
        "created_at": "2021-04-23T07:33:21.000000Z",
        "id": "9d0f2c36-0265-46c2-b3e4-c0c2d0b9eb92",
        "total": 1
    }
}

curl --location --request POST 'https://api-v2.acrcloud.com/api/fs-containers/10005/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--form 'file=@"/Users/olym/Downloads/886443683402_US4D80623007.mp3"' \
--form 'data_type="audio"'

curl --location --request POST 'https://api-v2.acrcloud.com/api/fs-containers/10005/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"data_type":"platforms", "url":"https://twitter.com/i/status/1439937773885079552"}'

import requests

url = "https://api-v2.acrcloud.com/api/fs-containers/10005/files"

payload={'data_type': 'audio'}
files=[
  ('file',('886443683402_US4D80623007.mp3',open('886443683402_US4D80623007.mp3','rb'),'application/octet-stream'))
]
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer token'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

import requests

url = "https://api-v2.acrcloud.com/api/fs-containers/10005/files"

payload={
    'data_type': 'platforms',
    'url':'https://www.youtube.com/watch?v=d_xYl5hpiRs'
}

headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer token',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api-v2.acrcloud.com/api/fs-containers/10005/files',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('file'=> new CURLFILE('886443683402_US4D80623007.lo'),'data_type' => 'fingerprint'),
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI2IiwianRpIjoiZGMzNjIyOThhMDAyN2NmZDMzZGU3MjBhYThhY2I0MTgyMzJhN2I5ZTA4MzdjNTI0M2UxODIxYzcwMTA5NDIwZTg0ZGJhY2Q4YTRhZWM0YzAiLCJpYXQiOjE2MTg4MjA1NTAuMDA2OTYzLCJuYmYiOjE2MTg4MjA1NTAuMDA2OTY3LCJleHAiOjE2NTAzNTY1NDkuOTkwNTQxLCJzdWIiOiIxOSIsInNjb3BlcyI6WyIqIl19.G7L5T2fQljhK2D1za669Q3cIIbyBT0oE8Z_IWQyL0sofZvIOYymVqW55w6b_nX6emkJj7JfylAI7q7-CVxXUN4tRcJCv9-AxFprhQubKvy59_6B5jd38jsOGHdlmMN5x7Mt3xl9WUPd1ODFg6Vqp3tR3nQ9J9eqUjrZgu54Yyx-1_gekBx87GCvcJxfmiDTBmr8J4Ze5099W_Bsj5UHGUb1X-GhNxVzfTFranTsvSEFDEA5jrBvNGIRkvqMUCx4jK7sJstlnlvTUmJ6WK0owl946ULiJhPe5jlM2_CKDckw81Ri6ecV1zAOWncTWi1Oa5qUkpEVf6pBtzk4_OLLjWUZ3MRz7xO2BiFYTuWxaQKNL9W4RhWbsf'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Show the one file or more files's results

GET https://api-v2.acrcloud.com/api/fs-containers/:container_id/files/:file_id

Suit for getting the youtube channels/playlists results

Path Parameters

Name

Type

Description

container_id

number

The container id

file_id

number

The file id

Query Parameters

Name

Type

Description

page

string

The page number

per_page

string

The results number per page

Headers

Name

Type

Description

Authorization

string

Bearer token

```json
{
    "data": [
        {
            "id": "e1cc5a16-e7b2-4261-9ab8-c20e1db70ac0",
            "uid": 1,
            "cid": 11655,
            "name": "/vod/video-3/01G6D3Z2SSDEDEGHP9ZSX8KC20/audio.mp4",
            "duration": 7,
            "uri": "audio_url:/01G6D3Z2SSDEDEGHP9ZSX8KC20/audio.mp4",
            "url": "https://test.com/01G6D3Z2SSDEDEGHP9ZSX8KC20/audio.mp4",
            "data_type": "audio_url",
            "engine": 1,
            "count": 1,
            "state": 1,
            "subscribed": 0,
            "detail": "",
            "created_at": "2022-07-06T03:50:33.000000Z",
            "updated_at": "2022-07-06T03:50:33.000000Z",
            "total": 1,
            "results": {
                "music": [
                    {
                        "played_duration": 7,
                        "offset": 0,
                        "type": "traverse",
                        "result": {
                            "album": {
                                "id": "3RQQmkQEvNCY4prGKE6oc5",
                                "name": "Un Verano Sin Ti"
                            },
                            "play_offset_ms": 87400,
                            "genres": [
                                {
                                    "name": "Latin"
                                }
                            ],
                            "title": "Efecto",
                            "result_from": 3,
                            "release_date": "2022-05-06",
                            "sample_end_time_offset_ms": 6160,
                            "sample_begin_time_offset_ms": 0,
                            "label": "Rimas Entertainment LLC",
                            "duration_ms": 213061,
                            "score": 100,
                            "db_begin_time_offset_ms": 80720,
                            "artists": [
                                {
                                    "id": "4q3ewBCX7sLwd24euuV69X",
                                    "name": "Bad Bunny"
                                }
                            ],
                            "db_end_time_offset_ms": 86880,
                            "external_ids": {
                                "isrc": "QM6MZ2214884",
                                "upc": "196626945068"
                            },
                            "acrid": "fd4e72b6dd70cdc0dde7f1f81a5c4df3",
                            "external_metadata": {
                                "musicbrainz": {
                                    "track": {
                                        "id": "782ee794-afb3-4adb-a1d7-c6fdc1d945de"
                                    }
                                },
                                "spotify": {
                                    "track": {
                                        "id": "5Eax0qFko2dh7Rl2lYs3bx",
                                        "name": "Efecto"
                                    },
                                    "album": {
                                        "name": "Un Verano Sin Ti"
                                    },
                                    "artists": [
                                        {
                                            "name": "Bad Bunny"
                                        }
                                    ]
                                },
                                "deezer": {
                                    "track": {
                                        "id": "1741494377",
                                        "name": "Efecto"
                                    },
                                    "album": {
                                        "name": "Un Verano Sin Ti"
                                    },
                                    "artists": [
                                        {
                                            "name": "Bad Bunny"
                                        }
                                    ]
                                },
                                "youtube": {
                                    "vid": "yO-XR4qXm1k"
                                }
                            }
                        }
                    }
                ]
            }
        }
    ]
}
```

curl --location --request GET 'https://api-v2.acrcloud.com/api/fs-containers/:your_container_id/files/f60c40d8-f35e-488e-bca4-105d85b080dc' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YourAccessToken'

import requests

url = "https://api-v2.acrcloud.com/api/fs-containers/:your_container_id/files/f60c40d8-f35e-488e-bca4-105d85b080dc"

payload={}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer token'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Delete the files

DELETE https://api-v2.acrcloud.com/api/fs-containers/:container_id/files/:ids

Path Parameters

Name

Type

Description

container_id

string

The container id

ids

string

The files ids, seperated by ","

Headers

Name

Type

Description

Authorization

string

Bearer token

Rescan the files

PUT https://api-v2.acrcloud.com/api/fs-containers/:container_id/files/:file_id/rescan

Path Parameters

Name

Type

Description

container_id

String

The container id

file_ids

String

The file ids, separate by ','

Headers

Name

Type

Description

Authorization

String

Bearer token

{
    // Response
}

curl --location --request PUT 'https://api-v2.acrcloud.com/api/fs-containers/10005/files/fd0cbc13-bb69-41ed-abbb-1ed6f25c3b02/rescan' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'

import requests

url = "https://api-v2.acrcloud.com/api/fs-containers/10005/files/fd0cbc13-bb69-41ed-abbb-1ed6f25c3b02/rescan"

headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer token'
}

response = requests.request("PUT", url, headers=headers)

Post result and state with json format to callback url

POST https://callback-url.com/path

Request Body

Name

Type

Description

file_id*

String

The file id

cid*

String

The container id

state*

String

1:Ready (Recognize results from a file.) -1: No results (No results were recognized from the file.) -2,-3: Error

results

String

if the state = 1, the results will be posted to the callback url

The format is: {

"music":[{},{}...],

"custom_files":[{},{},...],

"cover_files":[{},{},...] }

import requests

post_data = {
  'file_id':"c7331194-ccbe-4c3f-8e82-40d7b8358993",
  'state':1,
  'cid':1000,
  'results': {
        "music":[
                    {
                        "played_duration":164,
                        "type":"traverse",
                        "result":{
                            "album":{
                                "name":"Indie Brit Romance"
                            },
                            "play_offset_ms":10000,
                            "sample_begin_time_offset_ms":0,
                            "title":"Broken Skies 3",
                            "result_from":1,
                            "release_date":"2016-06-28",
                            "sample_end_time_offset_ms":9280,
                            "genres":[
                                {
                                    "name":"Indie"
                                },
                                {
                                    "name":"Singer"
                                },
                                {
                                    "name":"Songwriter"
                                }
                            ],
                            "label":"Audio Network",
                            "duration_ms":167000,
                            "score":100,
                            "db_begin_time_offset_ms":0,
                            "artists":[
                                {
                                    "name":"Bob Bradley"
                                },
                                {
                                    "name":"Matt Parker"
                                }
                            ],
                            "db_end_time_offset_ms":9280,
                            "external_ids":{
                                "isrc":"GBFFM1621637"
                            },
                            "acrid":"e8b02eab3fd1d2745f460fb608b7b5c1",
                            "external_metadata":[

                            ]
                        },
                        "offset":0
        }]
}
r =  requests.post(callback_url, json=post_data, timeout=3)

import requests

url = "https://api-v2.acrcloud.com/api/fs-containers"

payload={
  "name":"test", 
  "region":"eu-west-1", 
  "buckets":[8881,8882,"ACRCloud Music"],
  "audio_type":"linein",
  "engine":1,
  "policy":{"type":"traverse", "interval":0, "rec_length":10}
}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer token',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, json=payload)

print(response.text)

Download the integrated FS results

GET https://api-v2.acrcloud.com/api/fs-containers/:container_id/reports

The entire container fs results will be downloaded if no query parameter is specified.

Headers

Name

Value

Content-Type

application/json

Authorization

Bearer <token>

Path Parameters

Name

Type

Description

container_id

string

The fs container id

Query Parameters

Name

Type

Description

ids

string

filter by file ids, separate by commas

start_date

datetime

filter by start date, If filtered by time, both start_date and end_date need to exist simultaneously. format: YYYY-MM-DD

end_date

datetime

filter by end date, If filtered by time, both start_date and end_date need to exist simultaneously. format:YYYY-MM-DD

Examples

curl --location 'https://ap-api-v2.acrcloud.com/api/fs-containers/CONTIANER_ID/reports?ids=72eb3a04-5a49-4b5e-aab0-4bdd8f5fff6d' \
--header 'Authorization: Bearer YOUR_TOKEN' -o fs_report.zip
```

Last updated 3 days ago