TikTok Python SDK ma'lumotnomasi

Login Kit callback'idan kelgan code ni access va refresh token'li TokenBundle ga almashtiradi. Redirect handler'da bir marta chaqiriladi.

await tt.exchange_code(
    code: str,
    *,
    redirect_uri: str,
    code_verifier: Optional[str] = None,
) -> socialift.models.TokenBundle

• ▸Access token 24 soat, refresh token 365 kun amal qiladi.
• ▸login_url() da ishlatilgan redirect_uri ni aynan shu ko'rinishda bering; PKCE bilan boshlangan bo'lsa code_verifier ni ham qo'shing.
• ▸So'rov TikTok token endpoint'i talab qilganidek form-urlencoded yuboriladi; javobda access_token bo'lmasa ApiError.

Kalitlarni TIKTOK_CLIENT_KEY va TIKTOK_CLIENT_SECRET muhit o'zgaruvchilaridan o'qib klient yaratadi. Qo'shimcha argumentlar (scopes, business_id, timeout, license_key ...) konstruktorga uzatiladi.

TikTok.from_env(**kwargs) -> TikTok

• ▸O'zgaruvchi yo'q bo'lsa bo'sh satr olinadi va shu yerda xato bo'lmaydi: masalan login_url() chaqirilganda ConfigurationError chiqadi.

Foydalanuvchini yo'naltirish uchun TikTok Login Kit avtorizatsiya manzilini yasaydi. Sinxron metod, tarmoqqa so'rov yubormaydi.

tt.login_url(
    *,
    redirect_uri: str,
    state: Optional[str] = None,
    scopes: Optional[list[str]] = None,
    code_challenge: Optional[str] = None,
    code_challenge_method: Optional[str] = None,
    disable_auto_auth: bool = False,
) -> str

• ▸redirect_uri app'da ro'yxatdan o'tgan manzillardan biri bo'lishi kerak: to'liq https, statik (query va fragmentsiz), 512 belgigacha; bitta app'da 10 tagacha manzil.
• ▸scopes= berilmasa klient scope'lari ishlatiladi (konstruktorga berilmagan bo'lsa DEFAULT_SCOPES); TikTok ularni vergul bilan kutadi, SDK o'zi birlashtiradi.
• ▸Desktop ilovalar uchun PKCE majburiy: TikTok code_challenge ni verifier'ning SHA-256 hex ko'rinishida va code_challenge_method="S256" bilan kutadi. SDK ularni o'zi qo'shmaydi — ikkalasini bering, keyin code_verifier ni exchange_code() ga uzating.
• ▸client_key bo'sh bo'lsa ConfigurationError ko'tariladi.

url = tt.login_url(redirect_uri="https://siz.uz/cb", state=state)

Saqlangan refresh token bilan yangi access token oladi. Access token atigi 24 soat yashagani uchun buni jadval bo'yicha ishga tushiring.

await tt.refresh_token(refresh_token: str) -> socialift.models.TokenBundle

• ▸TikTok siz yuborgandan boshqa refresh_token qaytarishi mumkin — qaytgan bundle'dagi yangi qiymatni doim saqlang.
• ▸Refresh token 365 kun amal qiladi.

bundle = await tt.refresh_token(refresh_token)

Access token'ni bekor qiladi va app foydalanuvchi akkauntiga kirish huquqini yo'qotadi. Foydalanuvchi "uzish" tugmasini bosganda ishlatiladi.

await tt.revoke(token: str) -> bool

• ▸TikTok so'rovni qabul qilsa True qaytaradi; o'z bazangizdagi token'larni ham o'chiring.

await tt.revoke(token)

videos() orqali sahifalarni kezib, max_items tagacha videoni bitta ro'yxatga yig'adi. Ijodkor videolarini bazangizga sinxronlash uchun qulay.

await tt.iter_videos(
    token: str,
    *,
    max_items: int = 100,
    fields: Optional[str] = None,
) -> list[dict]

• ▸max_items (standart 100) — himoya chegarasi: katta akkauntda videolar minglab bo'ladi va cheksiz sikl rate limit'ga uriladi.
• ▸Har bir sahifa — ko'pi bilan 20 videoli alohida so'rov.

Kerakli ruxsatlar:video.list

page = await tt.videos(token, limit=20)
all_videos = await tt.iter_videos(token, max_items=100)

Ijodkor profilini Profile sifatida qaytaradi: id (open_id), ism, avatar, bio, obunachi, obuna va videolar soni. Login'dan keyin kim ulanganini ko'rsatish uchun qulay.

await tt.me(token: str, *, fields: Optional[str] = None) -> socialift.models.Profile

• ▸Scope'lar: open_id, avatar va display_name — user.info.basic; bio_description, profile_deep_link, is_verified — user.info.profile; follower_count, following_count, likes_count, video_count — user.info.stats.
• ▸Standart holatda shu maydonlarning hammasi so'raladi; faqat ruxsat berilgan scope'lar maydonlari kerak bo'lsa fields ga qisqaroq satr bering.
• ▸Profile.username va full_name ikkalasida ham display_name turadi; TikTok'ning xom obyekti raw da.

Kerakli ruxsatlar:user.info.basicuser.info.profileuser.info.stats

me = await tt.me(token)

Aniq ID'lar bo'yicha videolar ma'lumotini oladi — masalan, allaqachon ma'lum videolarning hisoblagichlari yoki muddati o'tadigan muqova havolalarini yangilash uchun.

await tt.video(
    video_ids: Iterable[str],
    token: str,
    *,
    fields: Optional[str] = None,
) -> list[dict]

• ▸TikTok bir so'rovda 20 tagacha ID qabul qiladi; SDK faqat birinchi 20 tasini jimgina oladi.
• ▸Natija tartibi siz bergan ID'lar tartibiga mos kelishiga tayanmang — id bo'yicha moslang.
• ▸video.list scope kerak.

Kerakli ruxsatlar:video.list

videos = await tt.video(["7300000000000000000"], token)

Ijodkorning o'z videolaridan bitta sahifani {"data", "cursor", "has_more"} ko'rinishida qaytaradi. Interfeysda sahifalab ko'rsatish uchun.

await tt.videos(
    token: str,
    *,
    limit: int = 20,
    cursor: Optional[int] = None,
    fields: Optional[str] = None,
) -> dict

• ▸TikTok bir so'rovda ko'pi bilan 20 ta video beradi; limit 1–20 oralig'iga keltiriladi.
• ▸cursor — millisekunddagi UTC Unix vaqti: eskiroq videolar uchun oldingi sahifadagi cursor ni uzating.
• ▸video.list scope kerak.

Kerakli ruxsatlar:video.list

page = await tt.videos(token, limit=20)
all_videos = await tt.iter_videos(token, max_items=100)

Ijodkorning joriy e'lon sozlamalarini qaytaradi: ruxsat etilgan privacy_level_options, max_video_post_duration_sec, izoh, duet va stitch o'chirilganmi. Har post oldidan chaqiring va post formasini shu javob asosida quring.

await tt.creator_info(token: str) -> dict

• ▸TikTok'ning Direct Post oqimi post boshlashdan oldin creator info so'ralishini kutadi.
• ▸Yuboriladigan privacy_level privacy_level_options ro'yxatidan biri bo'lishi kerak.
• ▸Javobda kunlik kvota maydoni yo'q; ijodkor API orqali kunlik post chegarasiga yetsa TikTok spam_risk_too_many_posts qaytaradi, SDK uni RateLimitError qiladi.
• ▸video.publish scope kerak.

Kerakli ruxsatlar:video.publish

info = await tt.creator_info(token)
print(info["privacy_level_options"])

Rasm havolalaridan foto (karusel) post yaratadi — to'g'ridan-to'g'ri joylaydi yoki draft=True bilan ijodkor inbox'iga qoralama qilib yuboradi.

await tt.publish_photos(
    token: str,
    *,
    photo_urls: list[str],
    title: Optional[str] = None,
    description: Optional[str] = None,
    privacy_level: str = 'SELF_ONLY',
    cover_index: int = 0,
    disable_comment: bool = False,
    auto_add_music: bool = True,
    draft: bool = False,
    wait: bool = False,
    brand_content: bool = False,
    brand_organic: bool = False,
) -> dict

• ▸35 tagacha rasm, JPEG yoki WebP, har biri 20 MB gacha; faqat tasdiqlangan domendagi havolalar (PULL_FROM_URL) qabul qilinadi.
• ▸title 90, description 4000 UTF-16 belgigacha; cover_index noldan sanaladi.
• ▸To'g'ridan-to'g'ri post uchun video.publish, draft=True (MEDIA_UPLOAD) uchun video.upload scope kerak. auto_add_music faqat to'g'ridan-to'g'ri postda ishlaydi.
• ▸draft=True bilan wait=True ishlatmang: holat ijodkor joylaguncha SEND_TO_USER_INBOX bo'lib qoladi.

Kerakli ruxsatlar:video.publish

result = await tt.publish_photos(token, photo_urls=["https://cdn.siz.uz/1.jpg"], title="Karusel")

publish_id bo'yicha postning joriy qayta ishlash holatini qaytaradi. O'zingiz so'rab turing yoki wait_publish() dan foydalaning.

await tt.publish_status(publish_id: str, token: str) -> dict

• ▸status qiymatlari: PROCESSING_UPLOAD (fayl yuklash), PROCESSING_DOWNLOAD (URL'dan olish), SEND_TO_USER_INBOX (qoralamalar), PUBLISH_COMPLETE, FAILED (sabab fail_reason da).
• ▸Har access token uchun daqiqasiga 30 ta so'rov.
• ▸publicaly_available_post_id (TikTok yozuvi shunday) faqat post ommaviy bo'lib, moderatsiyadan o'tgach keladi.

status = await tt.publish_status(publish_id, token)

Videoni ochiq havoladan yoki baytlar/fayl yo'lidan to'g'ridan-to'g'ri ijodkor profiliga joylaydi (Direct Post). {"publish_id"} qaytaradi, wait=True bo'lsa yakuniy status ham qo'shiladi.

await tt.publish_video(
    token: str,
    *,
    video_url: Optional[str] = None,
    video: Union[bytes, str, os.PathLike, NoneType] = None,
    title: Optional[str] = None,
    privacy_level: str = 'SELF_ONLY',
    disable_comment: bool = False,
    disable_duet: bool = False,
    disable_stitch: bool = False,
    cover_timestamp_ms: Optional[int] = None,
    brand_content: bool = False,
    brand_organic: bool = False,
    chunk_size: Optional[int] = None,
    wait: bool = False,
) -> dict

• ▸App TikTok audit'idan o'tmaguncha u joylagan hamma narsa maxfiy ko'rinish bilan cheklanadi — shu sababli privacy_level standarti SELF_ONLY.
• ▸video_url (PULL_FROM_URL) uchun domen yoki URL prefiksi tasdiqlangan, manzil https va redirect'siz bo'lishi kerak, aks holda url_ownership_unverified (PermissionError). TikTok yuklab olishni bir soatdan keyin to'xtatadi.
• ▸video= berilsa SDK faylni bo'laklab yuklaydi: 5 MB gacha — bir bo'lak, kattasi 5–64 MB li bo'laklar (chunk_size).
• ▸Post boshlash so'rovi har access token uchun daqiqasiga 6 ta bilan cheklangan. video.publish scope kerak.

Kerakli ruxsatlar:video.publishvideo.upload

result = await tt.publish_video(token, video_url="https://cdn.siz.uz/reel.mp4", title="Salom TikTok!",
                              privacy_level="SELF_ONLY", wait=True)

with open("reel.mp4", "rb") as f:
    result = await tt.publish_video(token, video=f.read(), title="Salom!")

Videoni e'lon qilmasdan ijodkorning TikTok inbox'iga qoralama sifatida yuboradi; ijodkor ilovada tahrirlab, o'zi joylaydi. Tavsif va maxfiylikni ijodkor tanlashi kerak bo'lganda ishlating.

await tt.upload_video(
    token: str,
    *,
    video_url: Optional[str] = None,
    video: Union[bytes, str, os.PathLike, NoneType] = None,
    chunk_size: Optional[int] = None,
    wait: bool = False,
) -> dict

• ▸video.upload scope kerak; bu yerda tavsif yoki maxfiylik parametri yo'q.
• ▸TikTok istalgan 24 soat ichida ko'pi bilan 5 ta kutilayotgan ulashishga ruxsat beradi.
• ▸Holat SEND_TO_USER_INBOX da to'xtaydi va faqat ijodkor joylagach PUBLISH_COMPLETE bo'ladi. wait=True aynan PUBLISH_COMPLETE ni kutadi, shuning uchun ijodkor ~2 daqiqada joylamasa ApiError bilan tugaydi.
• ▸Manba qoidalari publish_video() bilan bir xil: video_url uchun tasdiqlangan domen, video= bo'laklab yuklanadi.

Post PUBLISH_COMPLETE holatiga yetguncha publish_status() ni so'rab turadi va o'sha holatni qaytaradi. publish_video(wait=True) ichida aynan shu ishlatiladi.

await tt.wait_publish(
    publish_id: str,
    token: str,
    *,
    attempts: int = 40,
    delay: float = 3.0,
) -> dict

• ▸Standart: 40 urinish × 3 soniya, taxminan 2 daqiqa; attempts va delay bilan o'zgartiriladi.
• ▸FAILED bo'lsa fail_reason bilan ApiError; urinishlar tugasa ham ApiError.
• ▸SEND_TO_USER_INBOX ni yakun deb hisoblamaydi — inbox qoralamalari uchun ishlatmang.

TikTok API for Business orqali business akkaunt profili va kunlik kesimdagi metrikalarini qaytaradi. Akkaunt darajasidagi analitika paneli uchun.

await tt.business_account(
    token: str,
    *,
    business_id: Optional[str] = None,
    fields: Optional[list[str]] = None,
) -> dict

• ▸So'rov business-api.tiktok.com ga Access-Token sarlavhasi bilan ketadi — bu me() ishlatadigan Open API'dan alohida API oilasi; app'ingizda TikTok API for Business'ga kirish bo'lishi kerak.
• ▸business_id kerak (odatda ijodkorning open_id si): argument sifatida yoki klientda business_id= bilan bering, aks holda ConfigurationError.
• ▸fields — Python ro'yxati; SDK uni JSON massiv satri qilib yuboradi.

account = await tt.business_account(token)

TikTok API for Business orqali business akkaunt videolarini har biri bo'yicha ko'rsatkichlar bilan, sahifama-sahifa qaytaradi.

await tt.business_videos(
    token: str,
    *,
    business_id: Optional[str] = None,
    cursor: Optional[int] = None,
    max_count: int = 20,
    fields: Optional[list[str]] = None,
) -> dict

• ▸Keyingi sahifa uchun oldingi javobdagi cursor ni bering; max_count standarti 20.
• ▸business_id (argument yoki klient standarti) va TikTok API for Business'ga kirish kerak.

stats = await tt.business_videos(token, max_count=20)

Business akkauntning bitta videosidagi izohlarni qaytaradi; include_replies=True birinchi darajali izohlarga javoblarni ham qo'shadi.

await tt.comments(
    video_id: str,
    token: str,
    *,
    business_id: Optional[str] = None,
    cursor: Optional[int] = None,
    max_count: int = 30,
    include_replies: bool = False,
) -> dict

• ▸Javobning data obyekti qaytadi; keyingi sahifa cursor bilan, max_count standarti 30.
• ▸business_id va TikTok API for Business'ga kirish kerak.

comments = await tt.comments("7300000000000000000", token, max_count=30)

TikTok API for Business orqali izohni o'chiradi. Izohni o'chirmasdan ko'rinishdan olib tashlash kerak bo'lsa hide_comment() ni ishlating.

await tt.delete_comment(
    comment_id: str,
    token: str,
    *,
    business_id: Optional[str] = None,
) -> dict

• ▸business_id va TikTok API for Business'ga kirish kerak.

await tt.delete_comment(comment_id, token)

Business akkaunt videosidagi izohni yashiradi yoki hidden=False bilan qayta ko'rsatadi — qaytariladigan moderatsiya usuli.

await tt.hide_comment(
    comment_id: str,
    token: str,
    *,
    hidden: bool = True,
    business_id: Optional[str] = None,
) -> dict

• ▸action sifatida HIDE yoki UNHIDE yuboriladi; business_id kerak.

await tt.hide_comment(comment_id, token, hidden=True)

Business akkaunt nomidan izohga layk bosadi yoki liked=False bilan laykni olib tashlaydi.

await tt.like_comment(
    comment_id: str,
    token: str,
    *,
    liked: bool = True,
    business_id: Optional[str] = None,
) -> dict

• ▸action sifatida LIKE yoki UNLIKE yuboriladi; business_id kerak.

await tt.like_comment(comment_id, token, liked=True)

Izohni video tepasiga qadaydi yoki pinned=False bilan qadashni olib tashlaydi.

await tt.pin_comment(
    comment_id: str,
    token: str,
    *,
    pinned: bool = True,
    business_id: Optional[str] = None,
) -> dict

• ▸business/comment/top/ ga action sifatida TOP yoki UNTOP yuboriladi; business_id kerak.

await tt.pin_comment(comment_id, token, pinned=True)

Business akkaunt nomidan uning videosidagi izohga javob yozadi.

await tt.reply_comment(
    comment_id: str,
    token: str,
    text: str,
    *,
    video_id: Optional[str] = None,
    business_id: Optional[str] = None,
) -> dict

• ▸Argumentlar tartibi: comment_id, token, text; video_id SDK'da ixtiyoriy, lekin ma'lum bo'lsa bering.
• ▸business_id va TikTok API for Business'ga kirish kerak.

await tt.reply_comment(comment_id, token, "Rahmat!", video_id=video_id)

TikTok API for Business'ning istalgan endpoint'ini Access-Token sarlavhasi bilan chaqiradi. SDK o'ramagan Business API imkoniyatlari uchun.

await tt.business(
    path: str,
    token: str,
    *,
    method: str = 'POST',
    json: Optional[dict] = None,
    params: Optional[dict] = None,
) -> dict

• ▸path https://business-api.tiktok.com/open_api/v1.3/ ga nisbatan; oxirgi / avtomatik qo'shiladi.
• ▸Standart metod POST; javob tanasidagi code noldan farq qilsa xato ko'tariladi.
• ▸business_id avtomatik qo'shilmaydi — uni params yoki json ga o'zingiz qo'ying.

data = await tt.business("business/get/", token, method="GET", params={"business_id": open_id})

SDK'da o'rami hali yo'q istalgan Open API v2 endpoint'ini Authorization: Bearer sarlavhasi va TikTok xato tekshiruvi bilan chaqiradi. Xom JSON javobni qaytaradi.

await tt.call(
    path: str,
    token: str,
    *,
    method: str = 'POST',
    json: Optional[dict] = None,
    params: Optional[dict] = None,
) -> dict

• ▸path https://open.tiktokapis.com/v2/ ga nisbatan beriladi; TikTok talab qiladigan oxirgi / avtomatik qo'shiladi.
• ▸Standart metod POST; fields kabi query parametrlar params da, so'rov tanasi json da.
• ▸Argumentlar tartibi path, token (Ads.call da esa token birinchi).

Eng past darajadagi HTTP chaqiruv: to'liq URL'ga qayta urinishlar bilan so'rov yuboradi va TikTok HTTP 200 ichida qaytargan xatoni ham ko'taradi. Odatda avtorizatsiya sarlavhasini o'zi qo'shadigan call() yoki business() afzal.

await tt.request(method: str, url: str, **kwargs) -> Any

• ▸Avtorizatsiya sarlavhasi qo'shilmaydi — headers ni o'zingiz bering.
• ▸error.code "ok" dan farq qilsa (Open API) yoki code noldan farq qilsa (Business API) ApiError vorisi ko'tariladi.
• ▸Qayta urinishlar RetryPolicy bo'yicha (429 va 5xx javoblar).

Istalgan HTTP so'rovni yuboradi va JSON javobni qaytaradi — SDK'da hali alohida metodi yo'q endpoint uchun. Token va imzo parametrlarini (access_token, Meta uchun appsecret_proof — socialift.crypto.appsecret_proof) o'zingiz params yoki headers ga qo'shasiz.

await tt.request(
    method: str,
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    data: Optional[Any] = None,
    json: Optional[Any] = None,
    headers: Optional[Mapping[str, str]] = None,
) -> Any

• ▸params dagi None qiymatlar yuborilmaydi.
• ▸Limit (RateLimitError) va vaqtinchalik server xatolarida (HTTP 429, 500, 502, 503, 504) RetryPolicy bo'yicha qayta uriniladi; Retry-After sarlavhasi bo'lsa, shuncha kutiladi. Tarmoq uzilishi TransportError bo'lib chiqadi.

request("GET", ...) ning qisqa shakli.

await tt.get(url: str, **kw) -> Any

request("POST", ...) ning qisqa shakli.

await tt.post(url: str, **kw) -> Any

request("DELETE", ...) ning qisqa shakli.

await tt.delete(url: str, **kw) -> Any

Meta'ning kursorli sahifalashi (paging.next) bo'yicha yurib, barcha data elementlarini bitta ro'yxatga yig'ib qaytaradi.

await tt.paginate(
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    max_items: int = 500,
    page_size: int = 100,
) -> list[dict]

• ▸max_items (standart 500) — himoya chegarasi: yirik akkauntda ro'yxat o'n minglab yozuv bo'lishi mumkin. page_size — bitta so'rovdagi limit.

SDK o'zi yaratgan HTTP sessiyasini yopadi (tashqaridan berilgan sessiyaga tegmaydi). async with Client(...) ishlatilsa, o'zi chaqiriladi.

await tt.close() -> None