tiktok.product.202309.images.upload
POST/product/202309/images/uploadGọi qua 360: POST https://partner.quantri360.com/v1/tiktok/product/202309/images/upload
Endpoint ghi — thay đổi dữ liệu trên TikTok Shop. Key phải được tạo với tick "Cho phép gọi API ghi", nếu không sẽ nhận 403 write_not_allowed. Mỗi lần gọi được ghi nhật ký.
Mô tả API
Tải một ảnh lên TikTok Shop để dùng làm ảnh sản phẩm, ảnh biến thể, ảnh trong mô tả, ảnh bảng size, ảnh chứng nhận — trả uri gắn vào sản phẩm và url để hiển thị.
- Là API GHI — thay đổi dữ liệu thật trên TikTok Shop (tải tệp lên kho ảnh gian hàng); key cần quyền ghi.
- Gửi
multipart/form-data: trường tệpdata+ trường chữuse_case. 360 kiểm định dạng theo NỘI DUNG tệp (không theo tên / MIME) — chỉ nhận JPG / JPEG / PNG. - Ảnh
MAIN_IMAGEvàATTRIBUTE_IMAGEcó tỉ lệ ngoài khoảng 3:4 – 4:3 được sàn tự chuyển thành 1:1. use_casekhông bắt buộc ở sàn — nên gửi rõ để sàn kiểm đúng kích thước theo mục đích ảnh.
Request
Địa chỉ
POST https://partner.quantri360.com/v1/tiktok/product/202309/images/upload
Xác thực & gian hàng
| Tên | Vị trí | Kiểu | Mẫu | Mô tả |
|---|---|---|---|---|
| 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 | 100001 | Gian hàng (lấy ở GET /v1/platforms → shops[].platform_shop_id). BẮT BUỘC khi brand có > 1 gian hàng trên nền tảng; 360 bỏ tham số này trước khi chuyển tiếp. |
Tham số request
| Tên | Vị trí | Kiểu | Bắt buộc | Mẫu | Mô tả |
|---|---|---|---|---|---|
| data | body | file | Có | ao-dam.jpg | Tệp ảnh JPG / JPEG / PNG (1 tệp), ≤ 10MB, 100–20.000 px; ảnh chính 300–4000 px; bảng size cạnh ngắn ≥ 1024 px. |
| use_case | body | string | Không | MAIN_IMAGE | MAIN_IMAGE · ATTRIBUTE_IMAGE (ảnh biến thể) · DESCRIPTION_IMAGE · CERTIFICATION_IMAGE · SIZE_CHART_IMAGE · CUSTOMIZATION_IMAGE. |
Ví dụ request
curl -s -X POST "https://partner.quantri360.com/v1/tiktok/product/202309/images/upload?platform_shop_id=7494000000000000000" \ -H "Authorization: Bearer $KEY" \ -F "use_case=MAIN_IMAGE" \ -F "data=@ao-dam.jpg"
Python
import requests
from contextlib import ExitStack
KEY = "q360_live_..."
with ExitStack() as stack:
files = [("data", stack.enter_context(open("ao-dam.jpg", "rb")))]
r = requests.post("https://partner.quantri360.com/v1/tiktok/product/202309/images/upload", params={
"platform_shop_id": "7494000000000000000"
}, data={
"use_case": "MAIN_IMAGE"
}, files=files, headers={"Authorization": f"Bearer {KEY}"}, timeout=60)
print(r.status_code, r.json())Node.js
import { readFile } from 'node:fs/promises';
const KEY = 'q360_live_...';
const url = new URL('https://partner.quantri360.com/v1/tiktok/product/202309/images/upload?platform_shop_id=7494000000000000000');
const form = new FormData();
form.append("use_case", "MAIN_IMAGE");
form.append("data", new Blob([await readFile("ao-dam.jpg")]), "ao-dam.jpg");
const r = await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${KEY}` }, body: form });
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...';
$ch = curl_init('https://partner.quantri360.com/v1/tiktok/product/202309/images/upload?platform_shop_id=7494000000000000000');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, ['use_case' => 'MAIN_IMAGE', 'data' => new CURLFile('ao-dam.jpg')]);
echo curl_exec($ch);
curl_close($ch);Response
Tham số phản hồi (nguyên của TikTok Shop)
| Tên | Kiểu | Mẫu | Mô tả |
|---|---|---|---|
| code | int | 0 | 0 = thành công; khác 0 xem message (105001–105003 = token, 360 đã tự làm mới một lần). |
| message | string | Success | Thông điệp của TikTok. |
| request_id | string | 2025101900000000000000000000 | Mã request TikTok. |
| data | object | Dữ liệu. | |
| uri | string | tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe | Gửi vào `main_images[].uri`, `sku_img.uri`, `size_chart.image.uri` khi tạo / sửa sản phẩm. |
| url | string | Link xem ảnh — dùng trong thẻ `<img>` của mô tả. | |
| width | int | 720 | Sau khi sàn chỉnh tỉ lệ. |
| height | int | 720 | |
| use_case | string | MAIN_IMAGE |
Mẫu phản hồi
{
"code": 0,
"message": "Success",
"request_id": "202203070749000101…",
"data": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
"url": "https://p-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
"width": 720,
"height": 720,
"use_case": "MAIN_IMAGE"
}
}
Bắt đầu dùng
- Đăng ký tài khoản Partner
- Mở loại dữ liệu thuộc nhóm Sản phẩm ở trang nền tảng
- Tạo API key (tick kênh TikTok Shop)
- Gọi theo ví dụ ở trên