API de Contenido por hashtag de Xiaohongshu
Salud de la API
Ahora no se pueden leer los datos de salud, así que el estado reciente de esta API es desconocido. Eso no significa que esté caída.
Lee las notas públicas de una página de tema mediante topic_id, primero las más recientes o las más populares. Incluye texto completo, imágenes y datos del vídeo; una página no equivale a todo el tema.
Precio $5.56 por 1.000 solicitudes ($0.005556 por llamada). Las llamadas fallidas y los resultados vacíos no se cobran. Síncrona. Para tareas lentas añade "mode": "async" al cuerpo, recibe un job_id y consúltalo.
Parámetros de la solicitud
| Nombre | Ubicación | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|---|
Authorization | header | string | Sí | - | Bearer seguido de tu clave de API. Créala en la consola; nunca la pongas en una URL ni en un repositorio de código. |
platform | body | string | Sí | xiaohongshu | Identificador de la plataforma, valor fijo. |
action | body | string | Sí | hashtag | Identificador de la capacidad, valor fijo. |
topic_id | body.params | No declarado | Sí | - | ID de la página de tema para hashtag (24 caracteres) o un enlace a esa página, como https://www.xiaohongshu.com/page/topics/<ID>, un enlace de tema de la app o un enlace corto de Xiaohongshu. Sirven directamente los valores topics[].topic_id que devuelve note. No es el ID del objeto de etiqueta de una nota ni el nombre del tema. |
page_token | body.params | No declarado | No | - | Cursor de paginación para las acciones comments, sub_comments, search, user_posts, search_users y hashtag: devuelve el valor next_page_token de una fila de la respuesta anterior para obtener la siguiente página; omítelo para empezar desde la primera página. Cada página es una llamada y se factura por solicitud. |
sort | body.params | enum | No | - | Orden de las notas del tema: newest muestra primero las más recientes (igual que no enviarlo) y popular, las más populares. Mantén el mismo valor al paginar.Valores permitidosnewestpopular |
Ejemplos de código
Quiero recopilar datos con la capacidad «Contenido por hashtag» (xiaohongshu/hashtag) de la API de EveryInfra. Actúa como mi asistente de recopilación de datos y trabaja en tres pasos.
Paso 1: No escribas código todavía. Hazme preguntas en varias rondas, de una a tres cada vez, hasta que todo esto quede claro:
1. Para qué son los datos (de eso depende qué campos y cuántos datos necesito);
2. Qué recopilar exactamente: palabras clave, enlaces o ID, y cuántos;
3. Cuántas filas, si hay que paginar y el rango de fechas;
4. Qué campos necesito (consulta los campos disponibles en el catálogo enlazado al final y luego pregúntame);
5. Cómo guardar los resultados: CSV, Excel, JSON o una base de datos, y dónde;
6. En qué lenguaje escribir el script, dónde se ejecutará y si será una sola vez o de forma programada;
7. Cuánto quiero gastar como máximo.
Si una respuesta es vaga o contradice otra anterior, vuelve a preguntar. Si digo que no lo sé, sugiere una opción y pídeme que la confirme.
Paso 2: Antes de escribir código, explícame el plan para que lo apruebe: qué solicitudes enviarás, cuántas llamadas harás aproximadamente, cuánto costará según los precios del catálogo y cómo será el resultado.
Paso 3: Solo cuando lo apruebe, escribe el script siguiendo estas reglas de la API:
- Solicitud: POST https://api.everyinfra.com/api/v1/social
- Autenticación: cabecera Authorization: Bearer <API key>. Lee la clave de la variable de entorno EVERYINFRA_API_KEY; no la pongas en el código, los registros ni los commits.
- Cuerpo JSON de ejemplo (usa los nombres de campo y valores tal como están):
{
"platform": "xiaohongshu",
"action": "hashtag",
"params": {
"topic_id": "5be3ef92a514290001a15147"
}
}
- Para tareas lentas o volúmenes grandes, añade "mode": "async" al cuerpo. La API devuelve 202 y un job_id; consulta GET https://api.everyinfra.com/api/v1/jobs/{job_id} hasta que el estado sea succeeded o failed. Un 202 no es un éxito. Si una llamada síncrona devuelve un error de tiempo de espera (timeout), reenvía la misma solicitud con "mode": "async".
- Si el resultado trae next_page_token, pásalo como page_token para obtener la página siguiente sin cambiar los demás parámetros; cada página es una llamada.
- Los resultados fallidos o vacíos no generan un cargo final; lo reservado vuelve al saldo. Fíate del comprobante de facturación de la respuesta.
- Ante un 422, corrige la solicitud con los nombres de parámetro candidatos y los valores permitidos del mensaje de error; no adivines.
- Ante un 429 o un 503, espera el tiempo que indique Retry-After y vuelve a intentarlo; si la respuesta no trae Retry-After, ve alargando la espera entre intentos.
- Si se corta la red o el resultado es desconocido, conserva el request_id / job_id y consúltalo primero. No reenvíes automáticamente.
- Parámetros, valores permitidos, campos y precios: GET https://api.everyinfra.com/api/v1/social/catalog?platform=xiaohongshu (no requiere clave)[Definición OpenAPI (JSON)]Los ejemplos leen la clave de la variable de entorno EVERYINFRA_API_KEY; el código copiado nunca contiene tu clave.
Ejemplo de respuesta
Todavía no hay una muestra real para estos parámetros de ejemplo: se muestra la estructura de la respuesta y sus campos según el contrato, con … como marcadores. No es el resultado de una llamada real.
{
"id": "req_…",
"platform": "xiaohongshu",
"action": "hashtag",
"results": [
{
"id": …,
"url": …,
"title": …,
"text": …,
"like_count": …,
"collect_count": …,
"comment_count": …,
"share_count": …,
"posted_at": …,
"image_url": …,
"author_name": …,
"author_id": …,
"avatar_url": …,
"author_url": …,
"is_video": …,
"next_page_token": …,
"video_url": …,
"duration_sec": …,
"platform": …,
"images": …
}
],
"count": …,
"billing": { … },
"quota": { … }
}Campos de la respuesta
Los datos están en results. La tabla lista los campos que puede tener cada registro; los valores que la fuente no ofrece nunca se inventan.
| Campo | Significado |
|---|---|
id | Identificador único del registro en la plataforma de origen. Solo es único dentro de una plataforma; puede repetirse entre plataformas. |
urlPropio de la plataforma | Enlace del registro en Xiaohongshu. Los enlaces de search, note, profile y hashtag suelen incluir un token de acceso y se abren sin iniciar sesión (el token caduca; vuelve a llamar para obtener uno nuevo). Los enlaces de notas de user_posts no llevan token y lo necesitan para abrirse en el navegador: llama a note con el ID de la nota para obtener un enlace que se abra. Los enlaces de perfil de search_users tampoco llevan token; llama a profile con el user_id para obtener uno que se abra. |
title | Título. null cuando la plataforma no usa títulos (por ejemplo publicaciones solo de texto). |
textPropio de la plataforma | Texto de la nota o del comentario. note y hashtag devuelven el texto completo; search y user_posts pueden devolver un extracto recortado (unos 60 y 100 caracteres como máximo, respectivamente). Llama a note con el ID de la nota para obtener el texto completo. |
like_countPropio de la plataforma | Número de «me gusta». En resultados de notas y comentarios, los de ese elemento; en profile, el total que han recibido las notas de la cuenta. null significa que no es público o que no se obtuvo en esta llamada, no cero. |
collect_countPropio de la plataforma | Número de guardados. En resultados de notas, las veces que se guardó esa nota; en profile, el total de guardados de las notas de la cuenta. null significa que no es público o que no se obtuvo en esta llamada, no cero. |
comment_count | Comentarios. null significa no publicado, no 0. |
share_count | Veces compartido. null significa no publicado, no 0. |
posted_at | Fecha de publicación en ISO 8601, UTC (por ejemplo 2026-08-07T12:34:56+00:00). Las cadenas no estándar de la plataforma se transmiten tal cual, así que conviene analizarlas con tolerancia. null significa que la plataforma no la publica. |
image_url | Enlace de imagen. Las capacidades con varias imágenes pueden devolver una lista image_urls. |
author_name | Nombre visible del autor. |
author_idPropio de la plataforma | ID de usuario del autor. Puedes enviarlo a profile o user_posts. En los resultados de notas es el ID de 24 caracteres de la URL del perfil; en los de comentarios (comments, comments_batch, sub_comments) suele ser otra forma de 29 caracteres. Las dos formas de una misma persona no coinciden: antes de eliminar duplicados entre lotes, conviértelas con el user_id que devuelve profile. |
avatar_url | Enlace a la imagen de perfil. Algunas plataformas dan enlaces de CDN con tamaño que pueden caducar. |
author_urlPropio de la plataforma | Enlace al perfil del autor. No lleva token de acceso, así que no se abre sin iniciar sesión; la url que devuelve profile para el author_id sí se abre directamente. |
is_video | Si el elemento es un video. |
next_page_token | Conserva el significado de la plataforma |
video_urlPropio de la plataforma | Enlace de reproducción del vídeo (MP4). Está firmado y caduca: si necesitas conservarlo, descarga el archivo cuanto antes. null en las notas de imagen o si esta vez no se obtuvo. |
duration_secPropio de la plataforma | Duración del vídeo en segundos. null en las notas de imagen o si esta vez no se obtuvo. |
platform | Identificador de la plataforma de origen, igual que platform en la solicitud (por ejemplo xiaohongshu, tiktok). |
imagesPropio de la plataforma | Enlaces de imágenes. En note y hashtag, todas las imágenes de la nota en orden. En los resultados de comentarios (comments, comments_batch, sub_comments), las imágenes adjuntas al comentario, incluidos los stickers; un array vacío significa que no hay ninguna. null significa que esta vez no se obtuvo este dato. |
Errores y facturación
- 401
- Falta la clave o no es válida. La autenticación se comprueba antes que los parámetros, así que las solicitudes sin autenticar no ven el esquema de parámetros.
- 422
- Nombre o valor de parámetro incorrecto. El error enumera los parámetros y valores permitidos de esta capacidad y la opción más cercana; ocurre antes de cualquier cobro.
- 402
- Saldo insuficiente. Recarga primero.
- 429
- Se alcanzó el límite de solicitudes por minuto. Espera lo que indique Retry-After y vuelve a intentarlo.
- 503
- No se pudo completar ahora. Cualquier cargo de la llamada vuelve automáticamente a tu saldo, y el recibo de facturación de la respuesta indica el resultado real, también cuando aún no se conoce. No reenvíes a ciegas.
- 200 vacío
- La solicitud terminó sin datos y no se cobra (billing.reason = empty_result_refunded).