Audio Files

Upload an audio file/fingerprint

POST https://api-v2.acrcloud.com/api/buckets/:bucket_id/files

Upload the audio files or fingerprint to the specified bucket

Path Parameters

Name	Type	Description
bucket_id	number	The bucket id

Headers

Name	Type	Description
Authorization	string	Bearer token

Request Body

Name	Type	Description
file	object	The audio or fingerprint file. Required if the data_type is audio or fingerprint
title	string	The title of this file
data_type	string	the file type, the value should be audio, fingerprint, audio_url or acrid
user_defined	string	The user-defined metadata. JSON format.
url	string	audio file download URL. required if the data_type is audio_url
acrid	String	acrid from ACRCloud Music Database

200 File successfully uploaded.

{
    "data": {
        "uid": 1,
        "acr_id": "6d3e17559677cd79ecb0b7cd2c79bea0",
        "bucket_id": 8891,
        "state": 0,
        "title": "adsfad",
        "audio_id": "",
        "duration": "78.524082",
        "user_defined": {},
        "updated_at": "2020-12-24T08:49:17.000000Z",
        "created_at": "2020-12-24T08:49:17.000000Z",
        "id": 20
    }
}

Curl

curl --location --request POST 'https://api-v2.acrcloud.com/api/buckets/8891/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--form 'file=@"/Users/olym/Downloads/test.mp3"' \
--form 'title="adsfad"' \
--form 'data_type="audio"'

curl --location --request POST 'https://api-v2.acrcloud.com/api/buckets/8891/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"data_type":"audio_url", "title":"file-title", "user_defined":{"artists":"artist"}, "url":"https://your_host.com/AEA040700015_T1.mp3"}'

Python

import requests
import json

url = "https://api-v2.acrcloud.com/api/buckets/8891/files"

payload={'title': 'adsfad','data_type': 'audio',"user_defined":json.dumps({"key1":"value1", "key2":"value2"})}
files=[
  ('file',('test.mp3',open('/Users/olym/Downloads/test.mp3','rb'),'audio/mpeg'))
]
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer token'
}

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

print(response.text)

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api-v2.acrcloud.com/api/buckets/8891/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('/Users/olym/Downloads/test.mp3'),'title' => 'adsfad','data_type' => 'audio'),
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Authorization: Bearer token'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Nodejs

var axios = require('axios');
var FormData = require('form-data');
var fs = require('fs');
var data = new FormData();
data.append('file', fs.createReadStream('/Users/olym/Downloads/test.mp3'));
data.append('title', 'adsfad');
data.append('data_type', 'audio');

var config = {
  method: 'post',
  url: 'https://api-v2.acrcloud.com/api/buckets/8891/files',
  headers: { 
    'Accept': 'application/json', 
    'Authorization': 'Bearer token', 
    ...data.getHeaders()
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Ruby

require "uri"
require "net/http"

url = URI("https://api-v2.acrcloud.com/api/buckets/8891/files")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Authorization"] = "Bearer token"
form_data = [['file', File.open('/Users/olym/Downloads/test.mp3')],['title', 'adsfad'],['data_type', 'audio']]
request.set_form form_data, 'multipart/form-data'
response = http.request(request)
puts response.read_body

List the files

GET https://api-v2.acrcloud.com/api/buckets/:bucket_id/files

Path Parameters

Name	Type	Description
bucket_id	string	The bucket id

Query Parameters

Name	Type	Description
search	string	search by title
sort	string	sort by id or status, default is sort by id
order	string	asc or desc, default is asc
page	number	The page number
per_page	number	The results number per page
state	number	0:processing 1:Ready (audio files have been processed) -1: Error

Headers

Name	Type	Description
Authorization	string	Bearer token

200

{
    "data": [
        {
            "id": 20,
            "uid": 1,
            "bucket_id": 8891,
            "acr_id": "6d3e17559677cd79ecb0b7cd2c79bea0",
            "state": 0,
            "title": "adsfad",
            "user_defined": {},
            "duration": 79,
            "audio_id": "",
            "created_at": "2020-12-24T08:49:17.000000Z",
            "updated_at": "2020-12-24T08:49:17.000000Z"
        },
        {
            "id": 13,
            "uid": 1,
            "bucket_id": 8891,
            "acr_id": "224b26f7e3a3c44858be896c0fd9f45f",
            "state": 0,
            "title": "adsfad2",
            "user_defined": {},
            "duration": 79,
            "audio_id": "",
            "created_at": "2020-12-20T21:43:34.000000Z",
            "updated_at": "2020-12-20T21:43:49.000000Z"
        },
        {
            "id": 12,
            "uid": 1,
            "bucket_id": 8891,
            "acr_id": "0e5e7e376f7e177bbcb4da898f740a15",
            "state": 0,
            "title": "bucket",
            "user_defined": {
                "artist": "abc",
                "album": "334",
                "from": "ucf",
                "played_duration": 8,
                "ucf_id": "338229"
            },
            "duration": 206,
            "audio_id": "",
            "created_at": "2020-12-20T21:43:34.000000Z",
            "updated_at": "2020-12-20T21:43:49.000000Z"
        },
        {
            "id": 11,
            "uid": 1,
            "bucket_id": 8891,
            "acr_id": "6c875f014b9ca0ae89f44e1f93151b05",
            "state": 0,
            "title": "adsfad",
            "user_defined": {},
            "duration": 10,
            "audio_id": "",
            "created_at": "2020-12-20T21:43:34.000000Z",
            "updated_at": "2020-12-20T21:43:49.000000Z"
        },
        {
            "id": 10,
            "uid": 1,
            "bucket_id": 8891,
            "acr_id": "3ccdac434e9d08df333e8a5b4b8169fc",
            "state": 0,
            "title": "02c1d27e39",
            "user_defined": {
                "artist": "abc",
                "album": "334",
                "name": "asdf"
            },
            "duration": 14,
            "audio_id": "",
            "created_at": "2020-12-20T21:43:34.000000Z",
            "updated_at": "2020-12-20T21:43:49.000000Z"
        },
        {
            "id": 7,
            "uid": 1,
            "bucket_id": 8891,
            "acr_id": "625b970b5b837326fc927bd14cbfceb5",

            "state": 1,
            "title": "ddddaa",
            "user_defined": {},
            "duration": 300,
            "audio_id": "",
            "created_at": "2020-12-20T21:43:34.000000Z",
            "updated_at": "2020-12-20T21:43:49.000000Z"
        },
        {
            "id": 6,
            "uid": 1,
            "bucket_id": 8891,
            "acr_id": "87cd4888e660049f21199b812cc30346",
            "fp_id": null,
            "state": 1,
            "title": "test",
            "user_defined": {},
            "duration": 300,
            "audio_id": "",
            "created_at": "2020-12-20T21:43:34.000000Z",
            "updated_at": "2020-12-20T21:43:49.000000Z"
        }
    ],
    "links": {
        "first": "http://127.0.0.1:8080/api/buckets/8891/files?page=1",
        "last": "http://127.0.0.1:8080/api/buckets/8891/files?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://127.0.0.1:8080/api/buckets/8891/files",
        "per_page": "20",
        "to": 7,
        "total": 7
    }
}

Curl

curl --request GET 'https://api-v2.acrcloud.com/api/buckets/8891/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'

Python

import requests

url = "https://api-v2.acrcloud.com/api/buckets/8891/files"

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

response = requests.get(url, headers=headers)

print(response.text)

Update a file

PUT https://api-v2.acrcloud.com/api/buckets/:bucket_id/files/:id

Update the metadata of a file

Path Parameters

Name	Type	Description
bucket_id	number	The bucket id
id	number	The file id/acr_id

Headers

Name	Type	Description
Authorization	string	Bearer token

Request Body

Name	Type	Description
title	string	The file title.
user_defined	string	User-defined metadata, JSON format.

200

{
    "data": {
        "id": 20,
        "uid": 1,
        "bucket_id": 8891,
        "acr_id": "6d3e17559677cd79ecb0b7cd2c79bea0",
        "state": 0,
        "title": "update-title",
        "user_defined": {
            "artists": "update-artist"
        },
        "duration": 79,
        "audio_id": "",
        "created_at": "2020-12-24T08:49:17.000000Z",
        "updated_at": "2020-12-25T04:34:27.000000Z"
    }
}

Curl

curl --location --request PUT 'https://api-v2.acrcloud.com/api/buckets/8891/files/20' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"title":"update-title", "user_defined":{"artists":"update-artist"}}'

Delete files

DELETE https://api-v2.acrcloud.com/api/buckets/:bucket_id/files/:ids

Path Parameters

Name	Type	Description
bucket_id	number	The bucket id
ids	number	The file ids/acrids, seperated by ","

Headers

Name	Type	Description
Authorization	string	Bearer token

204

Curl

curl --location --request DELETE 'https://api-v2.acrcloud.com/api/buckets/8891/files/12,13' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'

Move the files to another bucket

PUT https://api-v2.acrcloud.com/api/buckets/:bucket_id/files/:ids/move

Move the files to another bucket

Path Parameters

Name	Type	Description
bucket_id	number	The bucket id that you want move the files to.
ids	string	One or multiple ids/acrids, separated by ","

Headers

Name	Type	Description
Authorization	string	Bearer token

201

Curl

curl --location --request PUT 'https://api-v2.acrcloud.com/api/buckets/8892/files/12,13' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'

Get one or multiple files

GET https://api-v2.acrcloud.com/api/buckets/:bucket_id/files/:ids

Path Parameters

Name	Type	Description
ids	string	The files ids or acrids. Seperated by ","
bucket_id	string	The bucket id

Headers

Name	Type	Description
Authorization*	string	Bearer token

200

{
    "data": [
        {
            "id": 12945472,
            "uid": 19,
            "bucket_id": 966,
            "acr_id": "75806fee10cf4405de502435129d6c06",
            "state": 1,
            "title": "api-test",
            "user_defined": {},
            "duration": 174,
            "created_at": "2020-10-14T11:02:15.000000Z",
            "updated_at": "2020-10-14T11:02:15.000000Z",
            "audio_id": "123"
        },
        {
            "id": 12403501,
            "uid": 19,
            "bucket_id": 966,
            "acr_id": "39a2d627dad781f5fbdb65e0e7d4d7c9",
            "state": 1,
            "title": "bucket-report-test",
            "user_defined": {
                "ucf_id": "718876"
            },
            "duration": 13,
            "created_at": "2020-09-01T03:50:23.000000Z",
            "updated_at": "2020-09-01T03:50:23.000000Z",
            "audio_id": ""
        },
        {
            "id": 12398516,
            "uid": 19,
            "bucket_id": 966,
            "acr_id": "904475b22cc6ffe6692b07dcd65b8ef8",
            "state": 1,
            "title": "music",
            "user_defined": {
                "ucf_id": "725868"
            },
            "duration": 8,
            "created_at": "2020-08-31T15:09:07.000000Z",
            "updated_at": "2020-08-31T15:09:07.000000Z",
            "audio_id": ""
        },
        {
            "id": 12398474,
            "uid": 19,
            "bucket_id": 966,
            "acr_id": "3b6fc496391a6a1758b6cd48da4f792b",
            "state": 1,
            "title": "happy",
            "user_defined": {
                "ucf_id": "718878"
            },
            "duration": 10,
            "created_at": "2020-08-31T15:05:40.000000Z",
            "updated_at": "2020-08-31T15:05:40.000000Z",
            "audio_id": ""
        },
        {
            "id": 12395185,
            "uid": 19,
            "bucket_id": 966,
            "acr_id": "fe34ec4ffbcec033ec2ed050f4b0daa7",
            "state": 1,
            "title": "test",
            "user_defined": {
                "ucf_id": "690303"
            },
            "duration": 10,
            "created_at": "2020-08-31T10:20:33.000000Z",
            "updated_at": "2020-08-31T10:20:33.000000Z",
            "audio_id": ""
        },
        {
            "id": 12158027,
            "uid": 19,
            "bucket_id": 966,
            "acr_id": "d66a31c5e62cf3e86874476da60db641",
            "state": 1,
            "title": "test",
            "user_defined": {
                "type": "advert",
                "from": "ucf",
                "played_duration": 16,
                "ucf_id": "725869"
            },
            "duration": 30,
            "created_at": "2020-08-11T04:03:31.000000Z",
            "updated_at": "2020-08-11T04:03:31.000000Z",
            "audio_id": ""
        },
        {
            "id": 11163949,
            "uid": 19,
            "bucket_id": 966,
            "acr_id": "601a566c3d4d77dfdb220e750384f842",
            "state": 1,
            "title": "Kesayanganku",
            "user_defined": {
                "artist": "Al Ghazali",
                "from": "ucf",
                "played_duration": 0,
                "ucf_id": "579162"
            },
            "duration": 240,
            "created_at": "2020-06-14T13:30:49.000000Z",
            "updated_at": "2020-06-14T13:30:49.000000Z",
            "audio_id": ""
        },
        {
            "id": 1849311,
            "uid": 19,
            "bucket_id": 966,
            "acr_id": "db397154fb9858f17373b5bf66be875a",
            "state": 1,
            "title": "Hiding my heart - Adele",
            "user_defined": {
                "title": "Hiding my heart",
                "artist": "Adele"
            },
            "duration": 208,
            "created_at": "2016-10-09T14:09:43.000000Z",
            "updated_at": "2016-10-09T14:09:49.000000Z",
            "audio_id": "12345"
        }
    ]
}

Curl

curl --location --request GET 'https://api-v2.acrcloud.com/api/buckets/966/files/13045360,13044049' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'

Dump all the files information in this bucket (only dump bucket data once a day)

GET https://api-v2.acrcloud.com/api/buckets/:bucket_id/dump

This is an asynchronous request. After the request is completed, you must wait and check the status through the interface. Once it becomes 1, you can download it using the down_url address.

Path Parameters

Name	Type	Description
bucket_id*	Number	Your bucket ID

Headers

Name	Type	Description
Authorization*	String	Bearer token

200: OK

{
    "status": 1,  //when status changes to 1, the dump is ready.  (default is 0)
    "down_url": "https://us-api-v2.acrcloud.com/api/buckets/6556/down/sFKD2eLbGX",
    //Download the file information from this URL when the status is 1
    "id": 6556,  //bucket ID
    "name": "us-bucket",  //bucket name
    "task_id": "sFKD2eLbGX"  //this dump task ID
}