API-Integration

TikTok-Posting-API für queue-sichere Multi-Account-Distribution

Setzen Sie TikTok-Posting-Workflows mit expliziter Statusverfolgung, retry-sicherer Orchestrierung und moderationsbewusster Handhabung für Teams im Produktionsmaßstab um.

Problem

Bei Skalierung scheitert die Distribution dort, wo das Posting noch manuell erfolgt: Upload-/Publish-Aktionen werden über viele Accounts, Zeitpläne und Moderationszustände hinweg fragil.

Ergebnis mit Ssemble

Ssemble unterstützt die Content-Generierung und Status-Orchestrierung, während Ihre TikTok-Posting-Schicht kontrollierte Veröffentlichungen mit Idempotency, Retries und nachvollziehbaren Job-Zuständen ausführt.

Wesentliches zur Implementierung

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

Integrationsarchitektur (Ingest → Verarbeitung → Poll/Webhook → Veröffentlichung)

1) Ingest

Speichern Sie Source-URL/File-URL + Zielaccount + scheduleAt + Idempotency Key in Ihrem Publisher-Job-Modell.

2) Verarbeitung

Rufen Sie POST /shorts/create auf, persistieren Sie die requestId und hängen Sie sie an nachgelagerte Posting-Jobs an.

3) Poll / Webhook

Überführen Sie Jobs mit GET /shorts/:id/status und Event-Fallbacks durch die Zustände processing/ready/failed.

4) Veröffentlichung

Lösen Sie die TikTok-Veröffentlichung mit Concurrency-Limits pro Account, Retry-Policy und finalem Statusabgleich aus.

Endpoint-Beispiele

POST /shorts/create— Short-Form-Asset vor dem Posting generieren
GET /shorts/:id/status— Verarbeitungs-Lifecycle und failureReason verfolgen
GET /shorts/:id— Metadaten der fertigen Ausgabe zum Posting abrufen

Hinweise zur Authentifizierung

Verwenden Sie X-API-Key serverseitig für Ssemble und halten Sie TikTok-OAuth-Tokens isoliert in Ihrem Posting-Service. Rotieren Sie jeden Schlüsselsatz unabhängig pro Umgebung.

Rate Limits und Retries

Behandeln Sie Generierung und Posting als getrennte Budgets. Serialisieren Sie mutierende Calls pro Zielaccount und respektieren Sie bei 429 reset/retryAfter mit exponential Backoff + Jitter.

Request-Beispiel

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"
}

Response-Beispiel

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

Beispiel für ein Fehlerszenario

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

Versionierung

Pinnen Sie Endpoint-Versionen und protokollieren Sie Upstream-Versionsmetadaten pro Request, damit Integrationsregressionen nachvollziehbar bleiben.

Support

Persistieren Sie für die Incident-Triage requestId + publish_id + Account-ID + error.code + Upstream-log_id in einem abfragbaren Datensatz.

Quickstart

Erstellen Sie SSEMBLE_API_KEY und legen Sie ihn in den Backend-Secrets ab.
Rufen Sie POST /shorts/create auf und persistieren Sie die requestId in Ihrer Job-Tabelle.
Pollen Sie GET /shorts/:id/status alle 10 Sekunden bis zum Endzustand.
Posten Sie bei completed über Ihre Server-Queue auf TikTok.
Behandeln Sie 429/5xx mit begrenzten Retries und stabilen Idempotency Keys.

TikTok-Posting-Dokumentation öffnen

Integration starten

1) Authentifizierung

API-Key-Format und Handhabung von Auth-Fehlern

2) Endpoint-Referenz

Create/Status/List/Delete-Contracts

3) Fehlerbehandlung

Muster für retrybare vs. terminale Fehler

4) Codebeispiele

Implementierungsfertige Integrations-Snippets

3-Schritt-Workflow

Generieren Sie Short-Form-Assets und speichern Sie requestId sowie den Publish-Kontext in Ihrer Job-Tabelle.
Verfolgen Sie die Verarbeitung per Status-Polling oder Webhooks und überführen Sie Jobs deterministisch in ready/failed-Zustände.
Veröffentlichen Sie auf TikTok mit Throttle-Kontrolle pro Account, Idempotency Keys und Abgleichsprotokollen.

Warum sich Teams für Ssemble entscheiden

Entwickelt für Multi-Account-Distributionsteams, bei denen Queue-Zuverlässigkeit wichtiger ist als einmaliger Erfolg.
Trennt Rendering- und Posting-Belange, sodass Fehler isoliert und behebbar bleiben.
Unterstützt moderationsbewusstes Zustandsmanagement: Der Abschluss eines Uploads bedeutet nicht immer die endgültige öffentliche Verfügbarkeit.

Nächster Schritt

TikTok-Posting-Quickstart öffnen Preise ansehen Entwicklerdokumentation

FAQ

Können wir einen erfolgreichen Upload als veröffentlicht behandeln?

Nicht immer. Halten Sie separate Zustände für uploaded, submitted, publish_complete und publicly_available vor, um False Positives zu vermeiden.

Welcher Schritt muss idempotent sein?

Mindestens die Initiierung der Veröffentlichung. Verwenden Sie einen stabilen Idempotency Key pro Job, damit Retries keine Duplikate erzeugen.

Polling oder Webhooks: Was sollten wir verwenden?

Verwenden Sie Webhooks als primären Weg, sofern verfügbar, und behalten Sie Polling als Fallback für Abgleich und verpasste Events bei.

Wie vermeiden wir 429-Bursts über viele Accounts hinweg?

Sharden Sie Queues nach Zielaccount und erzwingen Sie Concurrency-Limits pro Account statt einer einzigen globalen Burst-Queue.

Welche Logs sind für die Incident-Reaktion zwingend erforderlich?

Erfassen Sie requestId, publish_id, Account-ID, Statusübergänge und Error-Code, um deterministisches Debugging zu ermöglichen.

Garantiert dies eine bestimmte Dauer bis zum Abschluss der Moderation?

Nein. Moderationsfenster variieren, daher sollten Produktionssysteme das finale Verfügbarkeits-Timing als asynchron und variabel behandeln.