Upload a piece of music
POST/file/music/upload/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/file/music/upload/
Write endpoint — changes data on TikTok Business. The key must be created with "Allow write API calls" ticked, otherwise you get 403 write_not_allowed. Every call is logged.
Description
Use this endpoint to upload music and get the music ID, to add music to the Liked list or History list, or to remove music from the Liked list.
> Copyright Notice
Please make sure you have the right to use the music. If you infringe the copyright of the author, all responsibilities will be carried by you.
Comparing v1.2 and v1.3
The following table outlines the differences between v1.2 and v1.3 endpoints.
|Changes{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|Endpoint path|/v1.2/file/music/upload/|/v1.3/file/music/upload/|
|Request parameter data type |`advertiser_id`: number|`advertiser_id`: string|
|New request parameters|/|`music_scene`
`material_action`
`material_id`|
|Response parameter deprecated in v1.3 |/|`name`: string|
|New response parameters|/|`author`
`liked`
`cover_url`|Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/file/music/upload/
Authentication & shop
| Name | In | Type | Sample | Description |
|---|---|---|---|---|
| Authorization | header | header | Bearer q360_live_ab12cd34_… | Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand. |
| platform_shop_id | query | string | 7000000000000000001 | Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản. |
Request parameters
| Name | In | Type | Required | Sample | Description |
|---|---|---|---|---|---|
| music_scene | body | string | No | The scenario where the piece of music is used.
Enum values:
- CREATIVE_ASSET: Creative Tools.
- CAROUSEL_ADS: Non-Shopping Ads - Carousel format.
- CATALOG_CAROUSEL: Shopping Ads (VSA) - Carousel format.Default value: CREATIVE_ASSET. | |
| upload_type | body | string | No | When music_scene is set to CAROUSEL_ADS or CATALOG_CAROUSEL, you need to pass in either upload_type or material_action.
When music_scene is set to CREATIVE_ASSET or not passed, this field is optional and defaults to UPLOAD_BY_FILE.
The way you upload your music.
Enum values:
- UPLOAD_BY_FILE: To upload a piece of music via file.
- UPLOAD_BY_FILE_ID: To upload a piece of music via file ID. | |
| material_action | body | string | No | When music_scene is set to CAROUSEL_ADS or CATALOG_CAROUSEL, you need to pass in either upload_type or material_action.
Not supported when music_scene is set to CREATIVE_ASSET or not passed.
The type of operation you want to perform on a piece of music. You need to pass in material_id as well.
Enum values:
- ADD_TO_LIKED: To add a piece of music to the Liked list.
- ADD_TO_HISTORY: To add a piece of music to the History list.
- REMOVE_FROM_LIKED: To remove a piece of music from the Liked list. Note: The Liked list of an ad account can have up to 1,000 pieces of music. When the limit is reached, you cannot set this field to ADD_TO_LIKED to add more music to the Liked list. | |
| music_file | body | file | No | Required when upload_type is UPLOAD_BY_FILE or not specified.
Music file.
Note: When music_scene is set to CAROUSEL_ADS or CATALOG_CAROUSEL, the customized music file that you specify through this field should meet the following specifications requirements:
- File Type: MP3.
- File Size: no greater than 10 MB. | |
| music_signature | body | string | No | Required when upload_type is UPLOAD_BY_FILE or not specified.
Music MD5 (used for server verification). | |
| file_name | body | string | No | Valid only when upload_type is passed.
Music name.
Length limit: 1-100 characters.
The default is the local file name. | |
| file_id | body | string | No | Required when upload_type is UPLOAD_BY_FILE_ID.
The file_id of the file that you want to upload.
This field is for files that are uploaded to the file repository. You can get file_id via the Upload Files endpoints.
Note: When music_scene is set to CAROUSEL_ADS or CATALOG_CAROUSEL, the ID that you specify through this field should correspond to a customized music file that meets the following specifications requirements:
- File Type: MP3.
- File Size: no greater than 10 MB. | |
| material_id | body | string | No | Required when music_scene is set to CAROUSEL_ADS or CATALOG_CAROUSEL and material_action is passed.
Not supported when music_scene is set to CREATIVE_ASSET or not passed.
Material ID for the piece of music, which is used for adding music to the Liked list or History list, or for removing music from the Liked list.
To obtain a valid material ID , you can:
- upload a piece of customized music for Carousel Ads through this endpoint,
- OR retrieve the material IDs of music for Carousel Ads under an ad account via material_id returned by /file/music/get/. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/file/music/upload/" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/file/music/upload/",
params={},
json={},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60,
)
print(r.status_code)
print(r.json())Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/file/music/upload/');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({}),
});
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/file/music/upload/' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;Response
Response fields (as returned by TikTok Business)
| Name | Type | Sample | Description |
|---|---|---|---|
| code | number | Response code. For the complete list of response codes and descriptions, see Appendix - Return Codes. | |
| message | string | Response message. For details, see Appendix - Return Codes. | |
| data | object | Returned data. | |
| music_id | string | Music ID. | |
| material_id | string | Material ID. | |
| sources | string[] | Music source. `USER` means the advertiser's uploaded music; `SYSTEM` means the system music. | |
| author | string | Returned only for music that can be used in Carousel Ads. Author of the piece of music. | |
| liked | boolean | Returned only for music that can be used in Carousel Ads. Whether the piece of music is added to the Liked list. | |
| cover_url | string | Returned only for music that can be used in Carousel Ads. URL of the cover for the piece of music. | |
| url | string | Music link. Effective duration: 12h. | |
| duration | float | Music duration (in seconds). Only returned for system music. | |
| style | string | Music style. Only returned for system music. | |
| signature | string | Music file MD5. | |
| file_name | string | File Name. | |
| copyright | string | Copyright information. Enum values: - `MUSIC_FORBID_VIDEO_ALLOW` : Music is not allowed to download, but the generated video is allowed to download. - `MUSIC_FORBID_VIDEO_FORBID` : Both music and the generated video are not allowed to download. | |
| create_time | string | Creation time. Only returned for advertiser's music. UTC Time. Format: 2020-06-10 T07: 39: 14Z. | |
| modify_time | string | Modified time. Only returned for advertiser's music. Custom Soundtracks return this field, system music does not return this field. UTC Time. Format: 2020-06-10 T07: 39: 14Z. | |
| request_id | string | The log id of a request, which uniquely identifies the request. |
Response sample
HTTPS/1.1 200 OK
{
"message": "OK",
"code": 0,
"data": {
"copyright": "MUSIC_FORBID_VIDEO_ALLOW",
"url": "https://p9-dy.byteimg.com/obj/iesmusic-cn-local/v1/m/42b00000ca0384107766",
"file_name": "music_name_test",
"music_id": "6836297245562994693",
"material_id": "6836297245562994693",
"sources": [
"USER"
],
"create_time": "2020-12-06T07:08:09Z",
"modify_time": "2020-12-06T07:08:09Z",
"signature": "e360fd0e868c3183a0da849d38726739"
},
"request_id": "2020120607080801011515319101A3194C"
}
Get started
- Sign up for Partner
- Enable a data type of the Ads (Marketing API) group on the platform page
- Create an API key (tick the TikTok Business channel)
- Call it as in the examples above