Pourquoi la vérification de domaine pull_from_url de l'API TikTok rejette votre hôte

Qu'est-ce que la vérification de domaine pull_from_url de l'API TikTok ?

Passer la vérification de domaine pull_from_url de l'API TikTok signifie que TikTok a confirmé que vous contrôlez l'hôte qui sert votre fichier média, et tant que cette confirmation n'existe pas, aucun fichier n'est récupéré. C'est un contrôle de possession sur l'URL, pas sur la vidéo, et il intervient avant que le téléchargeur de TikTok n'ouvre la moindre connexion.

Le contrôle s'applique à chaque appel init qui porte source: "PULL_FROM_URL" :

Les photos n'ont aucune alternative. L'endpoint photo indique que « Only PULL_FROM_URL is allowed » dans source_info.source, donc la vérification n'est pas une optimisation pour publier des photos, c'est le prérequis entier. Les vidéos peuvent la contourner en passant à FILE_UPLOAD, même si les Content Sharing Guidelines de TikTok poussent dans l'autre sens : « If video resources are already on API Clients' servers, do not use FILE_UPLOAD; use PULL_FROM_URL instead. »

Comment vérifier un domaine auprès de TikTok ?

Vous ajoutez l'hôte comme propriété sur votre application, puis vous prouvez que vous le contrôlez via le DNS. Le Media Transfer Guide de TikTok décrit le flux en une phrase :

« 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. »

Sur la méthode elle-même, TikTok écrit : « To verify domain ownership, it is recommended that you add a signature string to the domain's DNS records. » Le mot « recommended » laisse entendre qu'une seconde voie existe, et TikTok n'en documente aucune. Aucune méthode par balise meta HTML n'est publiée, aucune méthode par dépôt de fichier, aucun type d'enregistrement nommé, aucune consigne de TTL, et aucune indication sur la durée de propagation tolérée ni sur une éventuelle revérification ultérieure. Si votre DNS est délégué à un prestataire que vous ne contrôlez pas, c'est ce vide documentaire qui vous bloque, et la documentation n'offre aucun repli.

Le mécanisme est celui qui se cache derrière un identifiant de domaine personnalisé sur Bluesky : une chaîne dans un enregistrement DNS prouve que celui qui demande la vérification tient aussi la zone.

Jusqu'où porte un domaine vérifié ?

Vers le bas, jamais vers le haut. TikTok énonce la règle puis donne l'exemple qui la rend concrète :

« 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. »

Relisez la seconde moitié, car c'est le piège. Vérifier un sous-domaine ne vérifie pas le parent. Une équipe qui vérifie cdn.example.com puis déplace ses fichiers vers example.com/cdn/ perd entièrement la vérification, alors que l'organisation possède évidemment toujours les deux. Le domaine apex est une propriété distincte et exige son propre enregistrement.

Les propriétés de type URL Prefix sont plus étroites encore, et TikTok en définit la forme avec précision : « A URL prefix consists of: https:// + host + path + /. » L'hôte « must be a domain and should not be an IP address », et la correspondance est littérale :

« 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. »

Notez que TikTok appelle un préfixe d'URL « the domain » dans son propre exemple de préfixe. La formulation est approximative, le comportement ne l'est pas : insérer 2023/ entre videos/ et user/ produit une chaîne qui ne commence plus par le préfixe vérifié, et la requête échoue. Toute arborescence de stockage qui place une date, un identifiant de locataire ou un numéro de partition avant le segment vérifié échouera de la même façon, ce qui plaide pour vérifier le domaine plutôt qu'un chemin profond.

Quelles sont les autres règles de pull_from_url ?

Trois conditions accompagnent la possession, et TikTok énonce chacune sans détour.

Le schéma est imposé : « The media URL must use "https" and should not redirect to another URL. » Les règles sur les préfixes sont plus brutales sur ce qui arrive dans le cas contraire : « Redirections are not followed. URLs that return HTTP 3xx are considered invalid. » Un service d'URL signées qui répond par un 302 vers le stockage, ou un CDN qui fait rebondir la requête d'un saut, reste invisible à un test navigateur et devient fatal ici. C'est l'un des rares endroits où une chaîne de redirections n'est pas une note de performance mais un échec pur et simple.

L'URL doit rester vivante pendant toute la tâche : « The URL must remain accessible for the entire duration of the download process, which times out one hour after the download task is initiated. » Les URL signées à durée de vie courte ont besoin d'une validité supérieure à une heure, pas à quelques minutes.

La bande passante a un plafond annoncé : « TikTok server's ingress bandwidth for file downloads can reach 100 Mbps. » TikTok ne publie aucun minimum, donc une origine à débit limité fait simplement tourner le chronomètre jusqu'à ce que le délai d'une heure mette fin à la tâche.

TikTok publie aussi une échappatoire pour les tests. Le Media Transfer Guide met en lien un MP4 d'exemple sur son propre CDN et précise que vous pouvez l'essayer « without any verification », ce qui permet d'exercer tout le flux init et statut avant que votre enregistrement DNS n'existe.

À quoi ressemble l'erreur url_ownership_unverified ?

Un hôte non vérifié renvoie un HTTP 403 avec error.code fixé à url_ownership_unverified. Le plus curieux, c'est que TikTok décrit ce même code de trois façons différentes sur trois pages en ligne :

« Video transfer method », « content transfer method » et « media transfer method » désignent le même mécanisme sous trois noms. Faites votre correspondance sur la chaîne du code, jamais sur le message. La troisième ligne est plus étrange encore que la formulation : url_ownership_unverified figure dans la spécification de réponse documentée de /v2/post/publish/cancel/, un endpoint qui ne prend qu'un publish_id et aucune URL. TikTok n'explique pas comment une requête d'annulation peut échouer à un contrôle de possession, et la liste des champs ne lui en donne aucun moyen.

Passer la vérification n'équivaut pas à réussir le téléchargement. Une fois la possession établie, les échecs se déplacent en aval, dans le fail_reason renvoyé par /v2/post/publish/status/fetch/, où video_pull_failed et photo_pull_failed partagent une même description : « 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. » Les problèmes de format et de taille arrivent séparément sous file_format_check_failed ou picture_size_check_failed, dans le même esprit que les exigences d'image d'Instagram qui rejettent un fichier pourtant téléversé sans accroc.

Un champ mérite d'être renseigné dans la même requête. is_aigc marque les médias synthétiques au moment de la publication, et les deux variantes du label de contenu généré par IA de TikTok se comportent très différemment selon que vous le définissez vous-même ou que TikTok le déduit.

Questions fréquentes

Vérifier example.com vérifie-t-il aussi cdn.example.com ?

Oui. TikTok indique que « all paths under that domain or its subdomains are considered owned by the developer application », donc un apex vérifié couvre ses sous-domaines. L'inverse échoue : vérifier cdn.example.com laisse example.com non vérifié.

Puis-je utiliser une adresse IP ou une URL http simple ?

Non aux deux. TikTok exige que « The media URL must use "https" », et la définition du préfixe d'URL précise que l'hôte « must be a domain and should not be an IP address. »

Pourquoi mon URL S3 ou Cloud Storage signée échoue-t-elle à la vérification ?

Le plus souvent parce que l'hôte du bucket n'est pas une propriété de votre application, ou parce que l'URL signée répond par une redirection. TikTok ne suit pas les redirections et considère toute réponse HTTP 3xx comme invalide, donc le saut vers le backend de stockage met fin à la tentative.

Combien d'URL de photos une requête peut-elle porter ?

Jusqu'à 35. L'endpoint photo décrit photo_images comme « An array containing up to 35 photo content URLs. The URLs must be publicly accessible and verified by your app », et chacune de ces URL est soumise au même contrôle de possession.

La fenêtre d'une heure démarre-t-elle à l'init ou au premier octet ?

Au démarrage de la tâche. TikTok dit que le téléchargement « times out one hour after the download task is initiated », donc une origine lente consomme le même chronomètre qu'un gros fichier, et la tâche se termine en video_pull_failed plutôt que d'attendre.

Puis-je annuler un téléchargement déjà en cours ?

Au mieux des efforts possibles. /v2/post/publish/cancel/ prend le publish_id, et TikTok prévient : « it is not feasible to cancel downloads that are nearing completion or already in the file processing state. » Une annulation réussie remonte ensuite sous la raison d'échec publish_cancelled.

Puis-je complètement éviter la vérification de domaine de TikTok ?

Seulement si tu publies une vidéo. Passer la méthode de transfert à FILE_UPLOAD supprime la vérification de propriété, même si les Content Sharing Guidelines de TikTok recommandent l'inverse pour une vidéo déjà présente sur ton serveur. Pour les photos, cette option n'existe pas : le endpoint photo n'autorise que PULL_FROM_URL, donc la vérification y est obligatoire.

Puis-je tester PULL_FROM_URL avant que mon enregistrement DNS existe ?

TikTok publie exactement une exception pour ça. Le Media Transfer Guide renvoie vers un MP4 d'exemple hébergé sur son propre CDN et précise qu'il fonctionne "sans aucune vérification", ce qui permet de tester tout le flux init et status avant d'ajouter un enregistrement DNS. Ça ne couvre que ce fichier précis, pas tes propres médias.

À quelle vitesse TikTok télécharge-t-il le fichier depuis mon URL ?

Jusqu'au plafond indiqué par TikTok, 100 Mbps de bande passante entrante pour les téléchargements de fichiers. TikTok ne publie aucun minimum pour ton origine, donc un serveur bridé laisse simplement s'écouler la fenêtre d'une heure jusqu'à ce que la tâche se termine en video_pull_failed ou photo_pull_failed.

Quelle est la différence entre url_ownership_unverified et video_pull_failed ?

url_ownership_unverified est la vérification en amont : TikTok rejette l'appel init avec un HTTP 403 avant même d'ouvrir une connexion vers ton URL. video_pull_failed, et son équivalent pour les photos, photo_pull_failed, survient plus tard, une fois la vérification de propriété passée, quand le téléchargement lui-même subit une erreur de connexion ou dépasse le délai d'une heure.