获取 Spark Ads 帖子信息
您可以使用本接口通过从帖子所有者处获得的授权码，查询有权发布为广告的 Spark Ads 帖子（视频）信息。
使用前需知
确保已从创作者（TikTok 帖子所有者）那里获得授权码。
你可以通过以下步骤，请创作者生成授权码：
1. 打开 TikTok 应用，点击想分享的帖子上的三点状图标。
2. 在分享菜单中点击“广告设置”。
3. 开启“广告授权”。
4. 选择授权时长。
5. 生成并复制授权码。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{20%}|v1.2{40%}|v1.3{40%}|
|---|---|---|
|接口路径|/v1.2/tt_video/info/|/v1.3/tt_video/info/|
|请求参数类型|advertiser_id: number|advertiser_id: string|
|请求参数名称|url(video_info中)|preview_url(video_info中)|
|返回参数类型|auth_end_time: datetime<br>auth_start_time: datetime<br>id(anchor_list中): number<br>item_id(item_info中): number<br>video_id(video_info中): number|auth_end_time: string<br>auth_start_time: string<br>id(anchor_list中): string<br>item_id(item_info中): string<br>video_id(video_info中): string|
|返回参数名称和类型|stitch_from_item_id(item_info中): number<br>duet_from_item_id(item_info中): number|stitch_original_item_id(item_info中): string<br>duet_original_item_id(item_info中): string|
|新增返回参数|/|url(anchor_list中)<br>mentioned_item_ids<br>item_type<br>carousel_info（包含本对象数组内的所有参数）<br>status<br>spu_id<br>spu_name<br>store_id|
|废弃返回参数|/|id(video_info`中): number|
## 请求
**地址** https://business-api.tiktok.com/open_api/v1.3/tt_video/info/
**方法** GET
**Header**
``` xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌，可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。 |
|Content-Type {必填}|string|请求消息类型。<br>允许值: `"application/json"` 。|
参数
|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string| 广告主 ID。 |
|auth_code {必填}|string| Spark Ads 帖子的授权码。 <br><br><p><span style="color:darkred"><b>注意</b></span>：将授权码中的“+”替换为“%2B”。否则，可能会出现授权码无效的报错提示。例如，你可以替换授权码 “#XtjblzbEuOGK/BvHj4V/K0i71JL3Wu2fgRtOJrZSSf4SrPAedegtn+IH+UXr3f4=” 中的 “+”，传入 “#XtjblzbEuOGK/BvHj4V/K0i71JL3Wu2fgRtOJrZSSf4SrPAedegtn%2BIH%2BUXr3f4=”。|
示例
(code Java java)
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import org.apache.http.client.utils.URIBuilder;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
public class Demo {
private static final String ACCESS_TOKEN = "xxx";
private static final String PATH = "/open_api/v1.3/tt_video/info/";
private static final ObjectMapper mapper = new ObjectMapper();
/**
* Build request URL
*
* @param path Request path
* @return Request URL
*/
private static String buildUrl(String path) throws URISyntaxException {
URI uri = new URI("https", "business-api.tiktok.com", path, "", "");
return uri.toString();
}
/**
* Send GET request
*
* @param jsonStr:Args in JSON format
* @return Response in JSON format
*/
private static String get(String jsonStr) throws IOException, URISyntaxException {
OkHttpClient client = new OkHttpClient().newBuilder().build();
URIBuilder ub = new URIBuilder(buildUrl(PATH));
Map< String, Object > map = mapper.readValue(jsonStr, Map.class);
map.forEach((k, v) -> {
try {
ub.addParameter(k, v instanceof String ? (String) v : mapper.writeValueAsString(v));
} catch (JsonProcessingException e) {
e.printStackTrace();
}
});
URL url = ub.build().toURL();
Request request = new Request.Builder()
.url(url)
.method("GET", null)
.addHeader("Access-Token", ACCESS_TOKEN)
.build();
Response response = client.newCall(request).execute();
return response.body().string();
}
public static void main(String[] args) throws IOException, URISyntaxException {
String advertiser_id = ADVERTISER_ID;
String auth_code = AUTH_CODE;
// Args in JSON format
String myArgs = String.format("{\"advertiser_id\": \"%s\", \"auth_code\": \"%s\"}",advertiser_id, auth_code);
System.out.println(get(myArgs));
}
}
(/code)
(code Python python)
# coding=utf-8
import json
import requests
from six import string_types
from six.moves.urllib.parse import urlencode, urlunparse # noqa
ACCESS_TOKEN = "xxx"
PATH = "/open_api/v1.3/tt_video/info/"
def build_url(path, query=""):
# type: (str, str) -> str
"""
Build request URL
:param path: Request path
:param query: Querystring
:return: Request URL
"""
scheme, netloc = "https", "business-api.tiktok.com"
return urlunparse((scheme, netloc, path, "", query, ""))
def get(json_str):
# type: (str) -> dict
"""
Send GET request
:param json_str: Args in JSON format
:return: Response in JSON format
"""
args = json.loads(json_str)
query_string = urlencode({k: v if isinstance(v, string_types) else json.dumps(v) for k, v in args.items()})
url = build_url(PATH, query_string)
headers = {
"Access-Token": ACCESS_TOKEN,
}
rsp = requests.get(url, headers=headers)
return rsp.json()
if __name__ == '__main__':
advertiser_id = ADVERTISER_ID
auth_code = AUTH_CODE
# Args in JSON format
my_args = "{\"advertiser_id\": \"%s\", \"auth_code\": \"%s\"}" % (advertiser_id, auth_code)
print(get(my_args))
(/code)
(code PHP php)
$ACCESS_TOKEN = "xxx";
$PATH = "/open_api/v1.3/tt_video/info/";
/**
* Build request URL
* @param $path : Request path
* @return string
*/
function build_url($path)
{
return "https://business-api.tiktok.com" . $path;
}
/**
* Send GET request
* @param $json_str : Args in JSON format
* @return bool|string : Response in JSON format
*/
function get($json_str)
{
global $ACCESS_TOKEN, $PATH;
$curl = curl_init();
$args = json_decode($json_str, true);
/* Values of querystring is also in JSON format */
foreach ($args as $key => $value) {
$args[$key] = is_string($value) ? $value : json_encode($value);
}
$url = build_url($PATH) . "?" . http_build_query(
$args
);
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"Access-Token: " . $ACCESS_TOKEN,
),
));
$response = curl_exec($curl);
curl_close($curl);
return $response;
}
$advertiser_id = ADVERTISER_ID;
$auth_code = AUTH_CODE;
/* Args in JSON format */
$my_args = sprintf("{\"advertiser_id\": \"%s\", \"auth_code\": \"%s\"}", $advertiser_id, $auth_code);
echo get($my_args);
(/code)
(code curl http)
curl --get -H "Access-Token:xxx" \
--data-urlencode "advertiser_id=ADVERTISER_ID" \
--data-urlencode "auth_code=AUTH_CODE" \
https://business-api.tiktok.com/open_api/v1.3/tt_video/info/
(/code)
返回
|字段{37%}|类型{13%}|描述{50%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述，可查看[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息。更多信息可查看[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|data |object|返回数据。 |
#|auth_info |object| 授权信息。 |
##|auth_end_time |string| 授权码有效期结束的时间(UTC+0)。时间格式：2017-01-01 00:00:00。 |
##|auth_start_time |string| 授权码有效期开始的时间(UTC+0)。时间格式：2017-01-01 00:00:00。 |
#|item_info |object| Spark Ads 帖子信息。 |
##|auth_code |string| Spark Ads 帖子的授权码。|
##|item_id |string| Spark Ads 帖子的ID。|
##| item_type | string | Spark Ads 帖子类型。<br><br>枚举值： <ul><li>`VIDEO`：视频帖子。 </li><li>`CAROUSEL`：照片帖子。</li></ul>|
##|text |string| Spark Ads 帖子描述。 |
##| status | string | Spark Ads 帖子状态。<br><br>枚举值参见[枚举值 - TikTok 帖子状态](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-TikTok%E5%B8%96%E5%AD%90%E7%8A%B6%E6%80%81)。 |
##| carousel_info | object | 照片帖子信息。 <br> <br><p><span style="color:darkred"><b>注意</b></span>：`item_type` 为 `VIDEO` 时，本字段值为 null。 |
###| image_info | object[] | 照片帖子中使用的图片的信息。 <br><br> 图片返回的顺序与在照片帖子中的顺序一致。 |
####| image_url | string | 图片 URL。 <br><br>有效期：90 天。 |
####| image_height |integer | 图片高度，单位为像素。 |
####| image_width | integer | 图片宽度，单位为像素。 |
###| music_info | object[] | 照片帖子中使用的音乐的信息。<br><br><p><span style="color:darkred"><b>注意</b></span>：若照片帖子是从 TikTok 应用中直接发布且无音乐的帖子，则本字段的值将为 null 。 |
####| music_url| string | 音乐 URL。 <br><br>有效期：90 天。 |
####| music_duration | integer | 音乐时长，单位为秒。 |
##|stitch_original_item_id|string| 如果本帖子是另一帖子的拼接，本字段代表源帖子的视频ID。|
##|duet_original_item_id|string| 如果本帖子是另一帖子的合拍，本字段代表该源帖子的视频ID。|
##|is_multi_duet_stitch|boolean| 本拼接帖是否是另一拼接帖的拼接，或本合拍帖是否是另一合拍帖的合拍。|
##|mentioned_item_ids|string[]|如果本帖子提及了其他视频，本字段代表该源帖子的视频ID。<br>注意：帖子只能提及一个视频|
##|anchor_list | object []|Spark Ads 帖子中的锚点列表。 |
###|id|string | 锚点 ID。 |
###|title |string | 锚点标题。 |
###|status | string | 锚点状态。枚举值: `CHECK_ING` (锚点正在审核中), `CHECK_FAILED` (锚点审核未通过), `CHECK_SUCCESS` (锚点审核已通过)。|
###|product_regions |string[] | 广告可投放区域。|
###|url|string| 视频 URL。|
###| spu_id | string | 仅当帖子中包含商品锚点链接时返回本字段。 <br><br>该帖子绑定的商品的 SPU ID。 |
###| spu_name | string | 仅当帖子中包含商品锚点链接时返回本字段。 <br><br>该帖子绑定的商品的名称。|
###| store_id | string | 仅当帖子中包含商品锚点链接时返回本字段。 <br><br>商品所属的 TikTok Shop 的 ID。 |
#|user_info |object| TikTok 账户信息。 |
##|tiktok_name |string| TikTok 账户昵称。 |
##|identity_id |string| 认证身份ID。 |
##|identity_type |string| 认证身份类型。 |
#|video_info |object| 视频帖子信息。<br><br><p><span style="color:darkred"><b>注意</b></span>：`item_type` 为 `CAROUSEL` 时，`video_info` 对象中的字段值为 null。 |
##|bit_rate |integer|视频比特率，单位为位/秒。 |
##|duration |float|视频时长，单位秒。 |
##|size |integer|视频大小，单位byte。 |
##|width |integer|视频宽度。 |
##|height |integer|视频高度。 |
##|video_id|string| 视频ID。|
##|file_name|string| 视频名称。|
##|poster_url |string|视频封面 URL。有效期1小时，过期需重新获取。 |
##|preview_url |string|视频预览链接, 有效期1小时，过期需重新获取。 |
##|signature |string|视频文件MD5。 |
|request_id |string|请求的日志ID，唯一标识一个请求。 |
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"auth_info": {
"auth_start_time": "2022-07-08 07:32:45",
"auth_end_time": "2022-08-07 07:32:44"
},
"video_info": {
"file_name": "",
"height": 1280,
"size": 813340,
"width": 720,
"signature": "{{signature}}",
"duration": 1.881,
"preview_url": "{{preview_url}}",
"poster_url": "{{poster_url}}",
"bit_rate": {{bit_rate}},
"video_id": "{{video_id}}"
},
"item_info": {
"stitch_original_item_id": "0",
"auth_code": "{{auth_code}}",
"item_id": "{{item_id}}",
"anchor_list": null,
"text": "",
"is_multi_duet_stitch": false,
"duet_original_item_id": "0",
"carousel_info": null,
"item_type": "VIDEO"
},
"user_info": {
"identity_type": "AUTH_CODE",
"tiktok_name": "{{tiktok_name}}",
"identity_id": "{{identity_id}}"
}
}
}
(/code);