Warum TikTok API pull_from_url Domain-Verifizierung Ihren Host ablehnt

Was ist TikTok API pull_from_url Domain-Verifizierung?

Bestandene TikTok API pull_from_url Domain-Verifizierung bedeutet, dass TikTok bestätigt hat, dass Sie den Host kontrollieren, der Ihre Mediendatei ausliefert, und bevor diese Bestätigung vorliegt, wird nie eine Datei geholt. Es ist eine Eigentumsprüfung für die URL, nicht für das Video, und sie läuft ab, bevor der Downloader von TikTok auch nur eine Verbindung öffnet.

Die Prüfung gilt für jeden init-Call, der source: "PULL_FROM_URL" mitführt:

Für Fotos gibt es keine Alternative. Der Foto-Endpunkt hält fest, dass in source_info.source „Only PULL_FROM_URL is allowed“ gilt, deshalb ist die Verifizierung beim Foto-Posting keine Optimierung, sondern die komplette Voraussetzung. Videos können sie umgehen, indem sie auf FILE_UPLOAD wechseln, doch die Content Sharing Guidelines von TikTok drängen in die andere Richtung: „If video resources are already on API Clients' servers, do not use FILE_UPLOAD; use PULL_FROM_URL instead.“

Wie verifizieren Sie eine Domain bei TikTok?

Sie tragen den Host als Property in Ihrer App ein und weisen die Kontrolle darüber per DNS nach. Der Media Transfer Guide von TikTok beschreibt den Ablauf in einem Satz:

„To confirm ownership, log into the TikTok for Developers website and add your Domain or URL Prefix property to your application in the URL properties widget as shown below. You must have manage or write access to the property.“

Zur Methode selbst schreibt TikTok: „To verify domain ownership, it is recommended that you add a signature string to the domain's DNS records.“ Das Wort „recommended“ legt nahe, dass es einen zweiten Weg gibt, und TikTok dokumentiert keinen. Es gibt keine veröffentlichte Methode über ein HTML-Meta-Tag, keine Datei-Upload-Methode, keinen genannten Record-Typ, keine TTL-Empfehlung und keine Angabe dazu, wie lange die Propagierung dauern darf oder ob TikTok den Eintrag später erneut prüft. Wenn Ihr DNS bei einem Anbieter liegt, den Sie nicht kontrollieren, blockiert Sie genau diese undokumentierte Lücke, und die Doku bietet keinen Ausweg.

Die Mechanik dahinter ist dieselbe wie bei einem eigenen Domain-Handle auf Bluesky: Ein String in einem DNS-Record beweist, dass wer die Verifizierung angefordert hat, auch die Zone betreibt.

Wie weit reicht eine verifizierte Domain?

Nach unten, nie nach oben. TikTok nennt die Regel und liefert dann das Beispiel, das sie greifbar macht:

„Once the ownership of a domain is verified, all paths under that domain or its subdomains are considered owned by the developer application.“

„For example, if you have verified the domain static.example.com, then URLs like https://video.static.example.com/tiktok/example.mp4 are considered verified, while URLs like https://example.com/videos/example.mp4 are still considered unverified.“

Lesen Sie die zweite Hälfte noch einmal, denn dort sitzt die Falle. Eine verifizierte Subdomain verifiziert nicht die übergeordnete Domain. Ein Team, das cdn.example.com verifiziert und die Assets danach nach example.com/cdn/ verschiebt, verliert die Verifizierung vollständig, obwohl die Organisation offensichtlich weiterhin beides besitzt. Die Apex-Domain ist eine eigene Property und braucht einen eigenen Record.

URL-Prefix-Properties sind noch enger gefasst, und TikTok definiert die Form genau: „A URL prefix consists of: https:// + host + path + /.“ Der Host „must be a domain and should not be an IP address“, und der Abgleich erfolgt wörtlich:

„For example, if you have already verified the domain https://example.com/videos/user/, then URLs like https://example.com/videos/user/123/example.mp4 are considered verified, while URLs like https://example.com/videos/2023/user/123/example.mp4 are still considered unverified.“

Beachten Sie, dass TikTok im eigenen Prefix-Beispiel ein URL-Prefix „the domain“ nennt. Die Formulierung ist unsauber, das Verhalten nicht: Ein 2023/ zwischen videos/ und user/ erzeugt einen String, der nicht mehr mit dem verifizierten Prefix beginnt, und die Anfrage scheitert. Jedes Speicherlayout, das ein Datum, eine Mandanten-ID oder eine Shard-Nummer vor das verifizierte Segment setzt, scheitert genauso, was ein gutes Argument dafür ist, die Domain statt eines tiefen Pfads zu verifizieren.

Welche weiteren pull_from_url-Regeln gibt es?

Neben dem Eigentumsnachweis stehen drei Bedingungen, und TikTok formuliert jede davon knapp.

Das Schema liegt fest: „The media URL must use "https" and should not redirect to another URL.“ Die Prefix-Regeln werden deutlicher, was passiert, wenn sie es doch tut: „Redirections are not followed. URLs that return HTTP 3xx are considered invalid.“ Ein Signed-URL-Dienst, der mit einem 302 auf den Storage antwortet, oder ein CDN, das die Anfrage einmal weiterreicht, bleibt in einem Browsertest unsichtbar und ist hier fatal. Das ist eine der wenigen Stellen, an denen eine Redirect-Kette keine Performance-Fußnote ist, sondern ein glatter Fehlschlag.

Die URL muss den ganzen Job über erreichbar bleiben: „The URL must remain accessible for the entire duration of the download process, which times out one hour after the download task is initiated.“ Kurzlebige Signed URLs brauchen eine Lebensdauer von mehr als einer Stunde, nicht von ein paar Minuten.

Für die Bandbreite nennt TikTok eine Obergrenze: „TikTok server's ingress bandwidth for file downloads can reach 100 Mbps.“ Ein Minimum veröffentlicht TikTok nicht, deshalb lässt ein gedrosselter Origin einfach die Uhr ablaufen, bis der Ein-Stunden-Timeout die Aufgabe beendet.

Zum Testen veröffentlicht TikTok außerdem eine Hintertür. Der Media Transfer Guide verlinkt ein Beispiel-MP4 auf dem eigenen CDN und hält fest, dass Sie es „without any verification“ ausprobieren können, womit Sie den kompletten init- und Status-Ablauf durchspielen, bevor Ihr DNS-Record existiert.

Wie sieht der Fehler url_ownership_unverified aus?

Ein nicht verifizierter Host liefert HTTP 403 mit error.code gleich url_ownership_unverified. Interessant daran ist, dass TikTok denselben Code auf drei aktiven Seiten dreimal anders beschreibt:

„Video transfer method“, „content transfer method“ und „media transfer method“ meinen denselben Mechanismus unter drei Namen. Gleichen Sie den Code-String ab, nie die Meldung. Die dritte Zeile ist noch seltsamer als der Wortlaut: url_ownership_unverified steht in der dokumentierten Response-Spezifikation von /v2/post/publish/cancel/, einem Endpunkt, der nur eine publish_id und überhaupt keine URL entgegennimmt. TikTok erklärt nicht, wie eine Cancel-Anfrage an einer Eigentumsprüfung scheitern kann, und die Feldliste gibt ihr auch keine Möglichkeit dazu.

Eine bestandene Verifizierung ist nicht dasselbe wie ein erfolgreicher Download. Sobald das Eigentum geklärt ist, wandern Fehler stromabwärts in den fail_reason, den /v2/post/publish/status/fetch/ zurückgibt, wo video_pull_failed und photo_pull_failed sich eine Beschreibung teilen: „The TikTok server encountered a connection error while downloading the specified video resource, or the download is terminated since it can not be completed within the one-hour timeout.“ Format- und Größenprobleme kommen getrennt als file_format_check_failed oder picture_size_check_failed, ganz im Sinne der Bildanforderungen von Instagram, die eine Datei ablehnen, die problemlos hochgeladen wurde.

Ein Feld lohnt sich in derselben Anfrage. is_aigc markiert synthetische Medien schon beim Posten, und die beiden Varianten des TikTok-Labels für KI-Inhalte verhalten sich sehr unterschiedlich, je nachdem, ob Sie es setzen oder TikTok es ableitet.

Häufig gestellte Fragen

Verifiziert example.com auch cdn.example.com?

Ja. TikTok hält fest, dass „all paths under that domain or its subdomains are considered owned by the developer application“, eine verifizierte Apex-Domain deckt ihre Subdomains also ab. Umgekehrt klappt es nicht: Wer cdn.example.com verifiziert, lässt example.com unverifiziert.

Kann ich eine IP-Adresse oder eine einfache http-URL verwenden?

Nein, beides nicht. TikTok verlangt, dass „The media URL must use "https"“, und die Definition des URL-Prefix hält fest, dass der Host „must be a domain and should not be an IP address.“

Warum scheitert meine signierte S3- oder Cloud-Storage-URL an der Verifizierung?

Meist, weil der Bucket-Host keine Property Ihrer App ist oder weil die signierte URL mit einem Redirect antwortet. TikTok folgt keinen Redirects und wertet jede HTTP-3xx-Antwort als ungültig, der Sprung zum Storage-Backend beendet den Versuch also.

Wie viele Foto-URLs darf eine Anfrage enthalten?

Bis zu 35. Der Foto-Endpunkt beschreibt photo_images als „An array containing up to 35 photo content URLs. The URLs must be publicly accessible and verified by your app“, und jede einzelne dieser URLs unterliegt derselben Eigentumsprüfung.

Startet das Ein-Stunden-Fenster bei init oder beim ersten Byte?

Beim Start der Aufgabe. TikTok sagt, der Download „times out one hour after the download task is initiated“, ein langsamer Origin verbraucht also dieselbe Uhr wie eine große Datei, und die Aufgabe endet in video_pull_failed, statt zu warten.

Kann ich einen laufenden Download abbrechen?

Nur auf Best-Effort-Basis. /v2/post/publish/cancel/ nimmt die publish_id entgegen, und TikTok warnt, dass „it is not feasible to cancel downloads that are nearing completion or already in the file processing state.“ Ein erfolgreicher Abbruch taucht später als Fail-Reason publish_cancelled auf.

Kann ich die TikTok-Domain-Verifizierung komplett umgehen?

Nur wenn Sie ein Video posten. Der Wechsel der Transfer-Methode zu FILE_UPLOAD entfernt die Ownership-Prüfung, auch wenn TikToks eigene Content Sharing Guidelines für ein Video, das schon auf Ihrem Server liegt, genau das Gegenteil empfehlen. Bei Fotos gibt es diese Option nicht: Der Foto-Endpunkt erlaubt nur PULL_FROM_URL, also ist die Verifizierung dort Pflicht.

Kann ich PULL_FROM_URL testen, bevor mein DNS-Eintrag existiert?

TikTok veröffentlicht genau eine Ausnahme dafür. Der Media Transfer Guide verlinkt ein Beispiel-MP4 auf TikToks eigenem CDN und sagt, es funktioniere "ohne jede Verifizierung", sodass Sie den kompletten init- und status-Flow testen können, bevor Ihr DNS-Eintrag existiert. Das gilt aber nur für diese eine Datei, nicht für Ihre eigenen Medien.

Wie schnell lädt TikTok die Datei von meiner URL herunter?

Bis zu der von TikTok genannten Obergrenze von 100 Mbps Ingress-Bandbreite für Datei-Downloads. TikTok nennt keine Mindestgeschwindigkeit für Ihren Origin-Server, also läuft bei einem gedrosselten Server einfach die Uhr des einstündigen Zeitfensters ab, bis die Aufgabe mit video_pull_failed oder photo_pull_failed endet.

Was ist der Unterschied zwischen url_ownership_unverified und video_pull_failed?

url_ownership_unverified ist die vorgelagerte Prüfung: TikTok lehnt den init-Call mit HTTP 403 ab, bevor überhaupt eine Verbindung zu Ihrer URL aufgebaut wird. video_pull_failed, und sein Pendant für Fotos, photo_pull_failed, tritt später auf, nachdem die Ownership-Prüfung schon bestanden wurde, wenn der Download selbst an einem Verbindungsfehler scheitert oder das einstündige Zeitfenster überschreitet.