# Audio Files

## Upload an audio file/fingerprint

<mark style="color:green;">`POST`</mark> `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\_*&#x75;rl          |
| acrid         | String | acrid from ACRCloud Music Database                                                |

{% tabs %}
{% tab title="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
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
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"}'
```

{% endtab %}

{% tab title="Python" %}

```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)
```

{% endtab %}

{% tab title="PHP" %}

```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;
```

{% endtab %}

{% tab title="Nodejs" %}

```javascript
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);
});
```

{% endtab %}

{% tab title="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
```

{% endtab %}
{% endtabs %}

## List the files

<mark style="color:blue;">`GET`</mark> `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 | <p>0:processing<br>1:Ready (audio files have been processed)<br>-1: Error</p> |

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |

{% tabs %}
{% tab title="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
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

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

{% endtab %}

{% tab title="Python" %}

```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)

```

{% endtab %}
{% endtabs %}

## Update a file

<mark style="color:orange;">`PUT`</mark> `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. |

{% tabs %}
{% tab title="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"
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
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"}}'
```

{% endtab %}
{% endtabs %}

## Delete  files

<mark style="color:red;">`DELETE`</mark> `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 |

{% tabs %}
{% tab title="204 " %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

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

{% endtab %}
{% endtabs %}

## Move the files to another bucket

<mark style="color:orange;">`PUT`</mark> `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 |

{% tabs %}
{% tab title="201 " %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

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

{% endtab %}
{% endtabs %}

## Get one or multiple files

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | string | Bearer token |

{% tabs %}
{% tab title="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"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | Number | Your bucket ID |

#### Headers

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer token |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "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
}
```

{% endtab %}
{% endtabs %}