Por qué la verificación de dominio pull_from_url de la API de TikTok rechaza tu host

¿Qué es la verificación de dominio pull_from_url de la API de TikTok?

Superar la verificación de dominio pull_from_url de la API de TikTok significa que TikTok ha confirmado que controlas el host que sirve tu archivo multimedia, y mientras esa confirmación no exista nunca se descarga ningún archivo. Es una comprobación de propiedad sobre la URL, no sobre el vídeo, y ocurre antes de que el descargador de TikTok abra una sola conexión.

La comprobación se aplica a cada llamada init que lleva source: "PULL_FROM_URL":

Las fotos no tienen alternativa. El endpoint de fotos indica que "Only PULL_FROM_URL is allowed" en source_info.source, así que la verificación no es una optimización para publicar fotos, es el requisito entero. Los vídeos pueden esquivarla cambiando a FILE_UPLOAD, aunque las Content Sharing Guidelines de TikTok empujan en sentido contrario: "If video resources are already on API Clients' servers, do not use FILE_UPLOAD; use PULL_FROM_URL instead."

¿Cómo se verifica un dominio con TikTok?

Añades el host como propiedad en tu app y luego demuestras que la controlas mediante DNS. La Media Transfer Guide de TikTok describe el flujo en una frase:

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

Sobre el método en sí, TikTok escribe: "To verify domain ownership, it is recommended that you add a signature string to the domain's DNS records." La palabra "recommended" da a entender que existe una segunda vía, y TikTok no documenta ninguna. No hay método publicado con etiqueta meta de HTML, ni método de subida de archivo, ni tipo de registro nombrado, ni indicación de TTL, ni una sola frase sobre cuánto puede tardar la propagación o sobre si TikTok vuelve a comprobar el registro más adelante. Si tu DNS está delegado en un proveedor que no controlas, ese hueco sin documentar es justo lo que te bloquea, y la documentación no ofrece alternativa.

El mecanismo es el mismo que hay detrás de un handle de dominio propio en Bluesky: una cadena en un registro DNS demuestra que quien pidió la verificación también gestiona la zona.

¿Hasta dónde llega un dominio verificado?

Hacia abajo, nunca hacia arriba. TikTok enuncia la regla y después da el ejemplo que la concreta:

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

Lee esa segunda mitad otra vez, porque ahí está la trampa. Verificar un subdominio no verifica el dominio padre. Un equipo que verifica cdn.example.com y luego mueve los archivos a example.com/cdn/ pierde la verificación por completo, aunque la organización siga siendo dueña de ambos. El dominio apex es una propiedad aparte y necesita su propio registro.

Las propiedades de tipo URL Prefix son todavía más estrechas, y TikTok define la forma con precisión: "A URL prefix consists of: https:// + host + path + /." El host "must be a domain and should not be an IP address", y la coincidencia es literal:

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

Fíjate en que TikTok llama "the domain" a un prefijo de URL en su propio ejemplo de prefijo. La redacción es laxa, el comportamiento no: insertar 2023/ entre videos/ y user/ produce una cadena que ya no empieza por el prefijo verificado, y la solicitud falla. Cualquier estructura de almacenamiento que ponga una fecha, un ID de inquilino o un número de shard por delante del segmento verificado fallará igual, lo que es un buen argumento para verificar el dominio en lugar de una ruta profunda.

¿Cuáles son las demás reglas de pull_from_url?

Junto a la propiedad hay tres condiciones, y TikTok enuncia cada una sin rodeos.

El esquema es fijo: "The media URL must use "https" and should not redirect to another URL." Las reglas de prefijo son más secas sobre lo que pasa si redirige: "Redirections are not followed. URLs that return HTTP 3xx are considered invalid." Un servicio de URLs firmadas que responde con un 302 hacia el almacenamiento, o un CDN que rebota la solicitud un salto, es invisible en una prueba de navegador y letal aquí. Este es uno de los pocos sitios donde una cadena de redirecciones no es una nota al pie de rendimiento sino un fallo rotundo.

La URL tiene que seguir viva durante todo el trabajo: "The URL must remain accessible for the entire duration of the download process, which times out one hour after the download task is initiated." Las URLs firmadas de vida corta necesitan durar más de una hora, no más de unos minutos.

El ancho de banda tiene un techo declarado: "TikTok server's ingress bandwidth for file downloads can reach 100 Mbps." TikTok no publica ningún mínimo, así que un origen limitado en velocidad se dedica a consumir el reloj hasta que el tiempo de espera de una hora termina la tarea.

TikTok también publica una vía de escape para pruebas. La Media Transfer Guide enlaza un MP4 de ejemplo en su propio CDN y señala que puedes probarlo "without any verification", lo que permite ejercitar el flujo completo de init y status antes de que exista tu registro DNS.

¿Qué aspecto tiene el error url_ownership_unverified?

Un host sin verificar devuelve HTTP 403 con error.code puesto en url_ownership_unverified. Lo interesante es que TikTok describe el mismo código de tres formas distintas en tres páginas vivas:

"Video transfer method", "content transfer method" y "media transfer method" son el mismo mecanismo con tres nombres. Compara la cadena del código, nunca el mensaje. La tercera fila es más rara que la redacción: url_ownership_unverified aparece en la especificación de respuesta documentada de /v2/post/publish/cancel/, un endpoint que solo recibe un publish_id y ninguna URL. TikTok no explica cómo una solicitud de cancelación puede fallar una comprobación de propiedad, y la lista de campos no le deja ninguna forma de hacerlo.

Pasar la verificación no es lo mismo que lograr la descarga. Una vez resuelta la propiedad, los fallos se desplazan aguas abajo, al fail_reason que devuelve /v2/post/publish/status/fetch/, donde video_pull_failed y photo_pull_failed comparten una descripción: "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." Los problemas de formato y tamaño llegan aparte como file_format_check_failed o picture_size_check_failed, en la misma línea que los requisitos de imagen de Instagram rechazando un archivo que se subió perfectamente.

Hay un campo que vale la pena poner en esa misma solicitud. is_aigc marca el contenido sintético en el momento de publicar, y las dos variantes de la etiqueta de IA generada de TikTok se comportan de forma muy distinta según lo pongas tú o lo deduzca TikTok.

Preguntas frecuentes

¿Verificar example.com verifica también cdn.example.com?

Sí. TikTok indica que "all paths under that domain or its subdomains are considered owned by the developer application", así que un apex verificado cubre sus subdominios. Al revés no funciona: verificar cdn.example.com deja example.com sin verificar.

¿Puedo usar una dirección IP o una URL http simple?

Ni una ni otra. TikTok exige que "The media URL must use "https"", y la definición de prefijo de URL indica que el host "must be a domain and should not be an IP address."

¿Por qué mi URL firmada de S3 o Cloud Storage no pasa la verificación?

Normalmente porque el host del bucket no es una propiedad de tu app, o porque la URL firmada responde con una redirección. TikTok no sigue redirecciones y trata cualquier respuesta HTTP 3xx como inválida, así que el salto al backend de almacenamiento termina el intento.

¿Cuántas URLs de fotos puede llevar una sola solicitud?

Hasta 35. El endpoint de fotos describe photo_images como "An array containing up to 35 photo content URLs. The URLs must be publicly accessible and verified by your app", y cada una de esas URLs pasa por la misma comprobación de propiedad.

¿La ventana de una hora empieza en init o en el primer byte?

Al iniciarse la tarea. TikTok dice que la descarga "times out one hour after the download task is initiated", así que un origen lento quema el mismo reloj que un archivo grande, y la tarea acaba en video_pull_failed en lugar de esperar.

¿Puedo cancelar una descarga que ya está en curso?

Con el mejor esfuerzo posible. /v2/post/publish/cancel/ recibe el publish_id, y TikTok advierte de que "it is not feasible to cancel downloads that are nearing completion or already in the file processing state." Una cancelación con éxito aparece después como el motivo de fallo publish_cancelled.

¿Puedo saltarme por completo la verificación de dominio de TikTok?

Solo si publicas video. Cambiar el método de transferencia a FILE_UPLOAD elimina la comprobación de propiedad, aunque las propias Content Sharing Guidelines de TikTok recomiendan lo contrario para un video que ya está en tu servidor. Con fotos esa opción no existe: el endpoint de fotos solo permite PULL_FROM_URL, así que ahí la verificación es obligatoria.

¿Puedo probar PULL_FROM_URL antes de que exista mi registro DNS?

TikTok publica exactamente una excepción para esto. La Media Transfer Guide enlaza un MP4 de ejemplo alojado en su propio CDN y dice que funciona "sin ninguna verificación", así que puedes ejecutar todo el flujo de init y status antes de añadir un registro DNS. Solo cubre ese archivo concreto, no tus propios medios.

¿A qué velocidad descarga TikTok el archivo de mi URL?

Hasta el límite que TikTok indica: 100 Mbps de ancho de banda de entrada para descargas de archivos. TikTok no publica una velocidad mínima para tu origen, así que un servidor con el ancho de banda limitado simplemente deja correr el reloj de la ventana de una hora hasta que la tarea termina en video_pull_failed o photo_pull_failed.

¿Cuál es la diferencia entre url_ownership_unverified y video_pull_failed?

url_ownership_unverified es la comprobación previa: TikTok rechaza la llamada init con HTTP 403 antes de abrir siquiera una conexión a tu URL. video_pull_failed, y su equivalente para fotos, photo_pull_failed, aparece después, una vez superada la comprobación de propiedad, cuando la propia descarga sufre un error de conexión o supera el tiempo límite de una hora.