VI | EN
Message us on Messenger
Developer resources

Upload a piece of music — TikTok Business API

Upload a piece of music · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

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

NameInTypeSampleDescription
AuthorizationheaderheaderBearer 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_idquerystring7000000000000000001Tà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

NameInTypeRequiredSampleDescription
music_scenebodystringNoThe 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_typebodystringNoWhen 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_actionbodystringNoWhen 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_filebodyfileNoRequired 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_signaturebodystringNoRequired when upload_type is UPLOAD_BY_FILE or not specified. Music MD5 (used for server verification).
file_namebodystringNoValid only when upload_type is passed. Music name. Length limit: 1-100 characters. The default is the local file name.
file_idbodystringNoRequired 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_idbodystringNoRequired 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)

NameTypeSampleDescription
codenumberResponse code. For the complete list of response codes and descriptions, see Appendix - Return Codes.
messagestringResponse message. For details, see Appendix - Return Codes.
dataobjectReturned data.
music_idstringMusic ID.
material_idstringMaterial ID.
sourcesstring[]Music source. `USER` means the advertiser's uploaded music; `SYSTEM` means the system music.
authorstringReturned only for music that can be used in Carousel Ads. Author of the piece of music.
likedbooleanReturned only for music that can be used in Carousel Ads. Whether the piece of music is added to the Liked list.
cover_urlstringReturned only for music that can be used in Carousel Ads. URL of the cover for the piece of music.
urlstringMusic link. Effective duration: 12h.
durationfloatMusic duration (in seconds). Only returned for system music.
stylestringMusic style. Only returned for system music.
signaturestringMusic file MD5.
file_namestringFile Name.
copyrightstringCopyright 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_timestringCreation time. Only returned for advertiser's music. UTC Time. Format: 2020-06-10 T07: 39: 14Z.
modify_timestringModified 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_idstringThe 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

  1. Sign up for Partner
  2. Enable a data type of the Ads (Marketing API) group on the platform page
  3. Create an API key (tick the TikTok Business channel)
  4. Call it as in the examples above