Lo que max_video_post_duration_sec de creator_info de TikTok te dice antes de publicar

¿Qué devuelve max_video_post_duration_sec de creator_info de TikTok?

El campo max_video_post_duration_sec de creator_info de TikTok devuelve el vídeo más largo, en segundos, que este creador concreto puede publicar. La propia redacción de TikTok no deja sitio para una constante global:

"The longest video duration in seconds that the TikTok creator can post. Different users have different maximum video-duration privileges. Developers should use this field to stop video posts that are too long. IGNORE if your client only sends photo media through this API."

Llega desde un único endpoint que no recibe ningún cuerpo de solicitud:

El token de acceso identifica al creador, así que la llamada es una consulta de ficha más que una búsqueda. TikTok describe el propósito del endpoint en la misma frase que la pantalla que debe dibujar: "When rendering the Export to TikTok page, your app must invoke the API and use the latest creator information returned to display the account's available privacy level options and video/photo interaction settings."

¿Qué más devuelve el endpoint de creator info?

Ocho campos, y cada uno existe para cambiar lo que muestra tu pantalla de publicación:

El TTL de dos horas del avatar pasa desapercibido con facilidad y produce imágenes rotas en cualquier pantalla que cachee la URL durante una sesión. Los dos indicadores disabled meten dos causas distintas en un solo booleano: una cuenta privada y un ajuste explícito de "No one" devuelven true por igual, y la respuesta no te da forma de saber cuál es.

¿Por qué varía la duración máxima de vídeo según el creador?

Porque TikTok concede privilegios de duración por cuenta y no por plataforma. La Media Transfer Guide es la única página que da números:

"All TikTok creators can post 3-minute videos, while some have access to post 5-minute or 10-minute videos. The longest video a developer can send via the initialize Upload Video endpoint is 10 minutes. TikTok users may trim developer-sent videos inside the TikTok app to fit their accounts' actual maximum publish durations."

Eso da un suelo documentado de 180 segundos y un techo documentado de 600. La propia respuesta de ejemplo de TikTok no devuelve ninguno de los dos:

"max_video_post_duration_sec": 300

Trescientos segundos son el nivel intermedio, cinco minutos. El ejemplo encaja con los niveles, pero nada en la referencia dice que el campo esté restringido a 180, 300 y 600. Está tipado como int32 sin enum, así que un cliente que ramifica sobre tres valores fijos apuesta por una suposición sin documentar. Compara la respuesta con el vídeo que tienes, nunca con una constante.

El centro de ayuda para usuarios de TikTok tampoco cierra el hueco. Su artículo "Making a post" les dice a los creadores: "Select a maximum length for your video", y no publica ninguna cifra en toda la página, y por eso lo que se cuenta dentro de la app sobre cuánto puede durar un vídeo de TikTok y lo que cuenta la API se siguen separando. Para una integración, el campo de la API es el único número realmente autoritativo, y lo es solo para la cuenta cuyo token usaste.

¿Qué opciones de nivel de privacidad llegan con él?

privacy_level_options devuelve una lista distinta según la cuenta sea pública o privada, y TikTok detalla las dos:

Las dos listas solo comparten MUTUAL_FOLLOW_FRIENDS y SELF_ONLY. PUBLIC_TO_EVERYONE nunca aparece para una cuenta privada, y FOLLOWER_OF_CREATOR nunca aparece para una pública. La referencia de Direct Post lista los cuatro valores en el enum privacy_level sin esa división, así que leer el enum en lugar de la respuesta es la forma en que las integraciones acaban enviando un valor que la cuenta no puede usar.

El castigo es concreto. privacy_level_option_mismatch vuelve en init, y TikTok le adjunta una advertencia: "All clients are required to correctly display the creator account's privacy level options and honor the users' choice. Occurances of this error for product-use applications suggest violations to TikTok's product-use guidance."

Las reglas de UX son igual de prescriptivas. TikTok exige que "Users must manually select the privacy status from a dropdown and there should be no default value", que las interacciones desactivadas se muestren en gris y que ninguno de los interruptores de comentarios, Duet o Stitch empiece marcado. Sobre la duración, las mismas directrices dicen: "API clients must check if the duration of the to-be-posted video follows the max_video_post_duration_sec returned in the creator_info API." Recibir un valor no es cumplir. Bloquear la publicación sí.

Los clientes sin auditar reciben una lista todavía más corta. TikTok los restringe a la visibilidad SELF_ONLY y a "up to 5 users to post in a 24 hour window", con todas esas cuentas en privado en el momento de publicar.

Lo que TikTok deja sin resolver

Tres huecos merecen estar en una lista de comprobación en vez de descubrirse en producción.

El scope no encaja con el flujo. Query Creator Info requiere el scope video.publish. El endpoint Upload en /v2/post/publish/inbox/video/init/ requiere video.upload. Un cliente que solo deja borradores en la bandeja de entrada del creador tiene por tanto un token que no puede llamar al endpoint cuyo valor TikTok le manda respetar. TikTok nunca aborda el conflicto; la frase sobre recortar de la Media Transfer Guide es lo más parecido a una solución, ya que una subida demasiado larga a la bandeja de entrada acaba en manos del creador para que la recorte en vez de ser rechazada sin más.

Un rechazo puede llegar como HTTP 200. La tabla de errores de creator info lista spam_risk_too_many_posts, spam_risk_user_banned_from_posting y reached_active_user_cap bajo el estado HTTP "200 (intentional)". Un cliente que solo ramifica sobre códigos de estado lo lee como éxito y muestra una pantalla de publicación que no puede publicar. La indicación de TikTok es parar: "When the creator_info API returns that the creator can not make more posts at this moment, API Clients must stop the current publishing attempt and prompt users to try again later."

El tope de publicaciones se describe, no se publica. TikTok escribe que "There is a limit on the number of posts that can be made to a creator account in a 24-hour window via Direct Post API. The upper limit may vary among creators (typically around 15 posts per day/ creator account) and is shared across all API Clients using Direct Post." Ningún campo devuelve ese número, y "typically around" es toda la precisión que da TikTok, una afirmación más blanda que la cifra plana que hay detrás del límite de publicación de contenido de Instagram.

No hay mínimo documentado. La referencia de la API publica una duración máxima por creador y nada por el lado bajo. Un vídeo demasiado corto solo aparece a posteriori, como el motivo de fallo duration_check_failed de /v2/post/publish/status/fetch/, descrito como "Video does not meet our duration restrictions."

Trata la llamada de creator info como parte de cada publicación, no del alta inicial. Las opciones de privacidad, los indicadores de interacción y el límite de duración cambian en cuanto el creador toca un ajuste, y por eso cualquier herramienta que programe publicaciones de TikTok tiene que volver a consultar en el momento de publicar en lugar de reutilizar lo que guardó la semana pasada. El pie de texto que adjuntas se rige aparte, por el techo de 2200 runas UTF-16 que cubre el límite de caracteres de los pies de TikTok.

Preguntas frecuentes

¿Devuelve max_video_post_duration_sec alguna vez algo que no sea 180, 300 o 600?

TikTok no promete esos tres valores. El campo es un int32, la referencia no publica ningún enum y solo la Media Transfer Guide menciona privilegios de 3, 5 y 10 minutos. Compara tu vídeo con el número devuelto y no con un conjunto fijo.

¿Qué pasa si publico un vídeo más largo que el límite devuelto?

Por Direct Post el trabajo falla con el motivo duration_check_failed. Por el endpoint Upload, TikTok indica que "TikTok users may trim developer-sent videos inside the TikTok app to fit their accounts' actual maximum publish durations", así que lo resuelve el creador durante la edición.

¿Puede una integración solo de fotos ignorar este campo?

Sí, y TikTok lo dice directamente. max_video_post_duration_sec, duet_disabled y stitch_disabled están marcados con "IGNORE if your client only sends photo media through this API."

¿Con qué frecuencia puedo llamar al endpoint de creator info?

Veinte veces por minuto por token de acceso de usuario. Es el techo publicado más alto de los endpoints de publicación, que están en 6 solicitudes por minuto para las llamadas init y 30 para el sondeo de estado.

¿Por qué duet_disabled es true si el creador nunca desactivó Duet?

Porque una cuenta privada activa el mismo indicador. TikTok devuelve true si "the creator account is private or they set the Duet interaction to "No one" in their privacy setting", y la respuesta no da forma de distinguir las dos causas.

¿El endpoint me dice si la cuenta es pública o privada?

Como campo no, pero privacy_level_options lo delata. Una lista que contiene PUBLIC_TO_EVERYONE pertenece a una cuenta pública, y una que contiene FOLLOWER_OF_CREATOR a una privada, ya que los dos valores nunca aparecen juntos.

¿Hay que consultar creator info antes de cada publicación o basta con hacerlo una vez al integrar la cuenta?

Antes de cada publicación, no solo al integrar la cuenta. Las opciones de privacidad, los indicadores de interacción y el límite de duración cambian en cuanto el creador ajusta una configuración, así que un valor obtenido la semana pasada puede quedar desactualizado. Las herramientas que programan publicaciones en TikTok deben volver a consultar en el momento de publicar en lugar de reutilizar una respuesta guardada.

¿Qué pasa si mi app deja que el creador elija un nivel de privacidad que no aparece en privacy_level_options?

TikTok devuelve el error privacy_level_option_mismatch en el init. Para aplicaciones de uso de producto, TikTok trata las repeticiones de ese error como señal de que se están violando sus directrices de uso de producto, ya que los clientes deben mostrar solo las opciones de privacidad reales de la cuenta.

¿Qué límites adicionales se aplican a una app de TikTok que todavía no ha pasado la auditoría?

TikTok restringe a los clientes no auditados al nivel de privacidad SELF_ONLY y a publicar para hasta 5 usuarios en una ventana de 24 horas. Cada una de esas cuentas debe ser privada en el momento de publicar.

¿Publica TikTok una cifra exacta del tope diario de publicaciones por cuenta de creador?

TikTok no publica ninguna cifra exacta. Describe un límite compartido entre todos los clientes de API que es "típicamente alrededor de 15 publicaciones por día/cuenta de creador" y puede variar según el creador, sin que ningún campo de la respuesta devuelva ese número.