API-integraatio

TikTok Posting API turvalliseen, jonopohjaiseen usean tilin jakeluun

Toteuta TikTok-julkaisutyönkulkuja eksplisiittisellä tilaseurannalla, retry-turvallisella orkestroinnilla ja moderointitietoisella käsittelyllä tuotantomittakaavan tiimeille.

Ongelma

Mittakaavassa jakelu epäonnistuu siellä, missä julkaisu tehdään yhä manuaalisesti: upload- ja publish-toiminnot muuttuvat hauraiksi useiden tilien, aikataulujen ja moderointitilojen kesken.

Tulos Ssemblen kanssa

Ssemble tukee sisällön luontia ja tilan orkestrointia, kun taas oma TikTok-julkaisukerroksesi suorittaa hallitut julkaisut idempotenssin, retry-toistojen ja tarkastettavien työtilojen avulla.

Toteutuksen perusteet

Base URL: https://aiclipping.ssemble.com/api/v1 (+ TikTok Open API for publish)

Integraatioarkkitehtuuri (ingest → prosessointi → poll/webhook → julkaisu)

1) Ingest

Tallenna lähde-URL / tiedosto-URL + kohdetili + scheduleAt + idempotency-avain julkaisijan työmalliisi.

2) Prosessointi

Kutsu POST /shorts/create, tallenna requestId ja liitä se myöhempiin julkaisutöihin.

3) Poll / Webhook

Siirrä työt processing/ready/failed-tilojen läpi käyttämällä GET /shorts/:id/status -kutsua ja tapahtumien varamekanismeja.

4) Julkaisu

Käynnistä TikTok-julkaisu tilikohtaisilla samanaikaisuuskatoilla, retry-käytännöllä ja lopullisella tilan täsmäytyksellä.

Endpoint-esimerkkejä

POST /shorts/create— Luo lyhytmuotoinen sisältöresurssi ennen julkaisua
GET /shorts/:id/status— Seuraa prosessoinnin elinkaarta ja failureReason-arvoa
GET /shorts/:id— Nouda valmiin lopputuloksen metadata julkaisua varten

Autentikointiohjeet

Käytä X-API-Key-avainta palvelinpuolella Ssemblen kanssa ja pidä TikTokin OAuth-tokenit eristettyinä julkaisupalvelussasi. Kierrätä kukin avainsarja itsenäisesti ympäristön mukaan.

Rate limit -rajat ja retry-toistot

Käsittele sisällön luontia ja julkaisua erillisinä budjetteina. Sarjallista muuttavat kutsut kohdetiliä kohti ja 429-vastauksen tullessa noudata reset/retryAfter-arvoja eksponentiaalisella backoffilla ja jitterillä.

Pyyntöesimerkki

POST /api/publish/tiktok
{
  "jobId": "job_01HT...",
  "requestId": "665a1b2c3d4e5f6a7b8c9d0e",
  "tiktokAccountId": "acct_kor_store_03",
  "scheduleAt": "2026-03-10T18:00:00Z",
  "idempotencyKey": "2f182b63-312f-4290-9222-7cf6f7f8f12d"
}

Vastausesimerkki

200 OK
{
  "jobId": "job_01HT...",
  "state": "publish_processing",
  "publishId": "v_inbox_file~v2.123456789",
  "nextCheckAt": "2026-03-10T18:00:30Z"
}

Virhetilanne-esimerkki

429 Too Many Requests
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-account posting throttle reached",
    "details": { "retryAfter": "2026-03-10T18:01:00Z" }
  }
}

Versiointi

Kiinnitä endpoint-versiot ja lokita upstream-versiometadata pyyntökohtaisesti, jotta integraatioregressiot ovat jäljitettävissä.

Tuki

Häiriöiden triageen tallenna requestId + publish_id + account id + error.code + upstream log_id yhteen kyseltävään tietueeseen.

Pikaopas

Luo SSEMBLE_API_KEY ja tallenna se backendin salaisuuksiin.
Kutsu POST /shorts/create ja tallenna requestId työtaulukkoosi.
Kysele GET /shorts/:id/status 10 sekunnin välein, kunnes saavutetaan lopputila.
Kun tila on completed, julkaise TikTokiin palvelinjonosi kautta.
Käsittele 429/5xx-virheet rajoitetuilla retry-toistoilla ja pysyvillä idempotency-avaimilla.

Avaa TikTok-julkaisun dokumentaatio

Aloita integraatio

1) Autentikointi

API-avaimen muoto ja autentikointivirheiden käsittely

2) Endpoint-viite

Create/status/list/delete-sopimukset

3) Virheenkäsittely

Retry-kelpoiset vs. lopulliset virhemallit

4) Koodiesimerkit

Toteutusvalmiit integraatiokatkelmat

3-vaiheinen työnkulku

Luo lyhytmuotoiset sisältöresurssit ja tallenna requestId sekä julkaisukonteksti työtaulukkoosi.
Seuraa prosessointia status-poll-kyselyillä tai webhookeilla ja siirrä työt deterministisesti ready/failed-tiloihin.
Julkaise TikTokiin tilikohtaisella throttle-hallinnalla, idempotency-avaimilla ja täsmäytyslokeilla.

Miksi tiimit valitsevat Ssemblen

Rakennettu usean tilin jakelutiimeille, joille jonon luotettavuus on tärkeämpää kuin yksittäinen onnistuminen.
Erottaa renderöinnin ja julkaisun toisistaan, joten virheet ovat eristettyjä ja palautettavissa.
Tukee moderointitietoista tilankäsittelyä: uploadin valmistuminen ei aina tarkoita lopullista julkista saatavuutta.

Seuraava vaihe

Avaa TikTok-julkaisun pikaopas Katso hinnoittelu Kehittäjädokumentaatio

UKK

Voimmeko käsitellä uploadin onnistumista julkaistuna?

Ei aina. Pidä erilliset tilat arvoille uploaded, submitted, publish_complete ja publicly_available väärien positiivisten välttämiseksi.

Minkä vaiheen on oltava idempotentti?

Vähintään julkaisun käynnistyksen. Käytä yhtä pysyvää idempotency-avainta työtä kohti, jotta retry-toistot eivät luo duplikaatteja.

Poll vai webhook: kumpaa meidän tulisi käyttää?

Käytä webhookeja ensisijaisena, kun ne ovat saatavilla, ja pidä poll-kysely varamekanismina täsmäytystä ja menetettyjä tapahtumia varten.

Miten vältämme 429-purskeet monilla tileillä?

Jaa jonot kohdetilin mukaan ja pakota tilikohtaiset samanaikaisuusrajat yhden globaalin purskejonon sijaan.

Mitkä lokit ovat pakollisia häiriötilanteiden hallintaan?

Kirjaa requestId, publish_id, account id, tilasiirtymät ja error code deterministisen virheenkorjauksen tueksi.

Takaako tämä moderoinnin valmistumisajan?

Ei. Moderointi-ikkunat vaihtelevat, joten tuotantojärjestelmien tulisi käsitellä lopullisen saatavuuden ajoitusta asynkronisena ja vaihtelevana.