REST APISin clave de APICORSJSON · PNG · HTML

Plataforma para desarrolladores MCAPI.TR

Documentación de API

La guía completa para desarrolladores de MCAPI.TR: servidores Minecraft Java, Legacy y Bedrock, iconos, banners, widgets, tendencias y estadísticas de la plataforma.

OpenAPI JSON Probar en vivo

URL basehttps://mcapi.tr/api/v1

01 — Inicio rápido

Obtén tu primera respuesta en segundos

Sin configuración ni claves. Elige un cliente, copia el ejemplo y ejecútalo.

curl

curl "https://mcapi.tr/api/v1/status/mc.hypixel.net"

02 — Área de pruebas API

Envía una solicitud en vivo desde tu navegador

La solicitud va directamente a la API de MCAPI.TR y la respuesta formateada aparece abajo.

03 — Referencia de endpoints

Todos los endpoints públicos

Abre una tarjeta para ver parámetros, caché y ejemplos ejecutables.

GET/api/v1/status

Estado de la API

Verifica disponibilidad, versión y hora del servidor. Endpoint ligero para monitores de disponibilidad.

application/json

Autenticación

No requiere clave de API

Caché

Ninguna

Content-Type

application/json

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/status"

Respuesta de ejemplo

json

{
  "status": "OK",
  "timestamp": "2026-09-08T20:12:00.000Z",
  "service": "mcapi.tr-engine",
  "version": "0.1.0"
}

GET/api/v1/status/:address

Estado del servidor Minecraft

Devuelve el estado de servidores Java, Legacy Java o Bedrock con jugadores, versión, MOTD, icono y latencia.

application/json

Autenticación

No requiere clave de API

Caché

60 segundos por defecto

Content-Type

application/json

Parámetros

Parámetro	Ubicación	Tipo	Predeterminado	Descripción
`address`*	path	string	—	Hostname o IP; se puede añadir un puerto: play.example.net:25565
`legacy`	query	boolean	false	Fuerza el protocolo ping de Java anterior a 1.7.2.
`bedrock`	query	boolean	false	Usa la consulta de Bedrock Edition; el puerto predeterminado pasa a 19132.

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/status/mc.hypixel.net"
curl "https://mcapi.tr/api/v1/status/bedrock.example.net:19132?bedrock=true"

Respuesta de ejemplo

json

{
  "query": {
    "host": "mc.hypixel.net",
    "port": 25565,
    "legacy": false,
    "bedrock": false
  },
  "server_id": "f17d4f75-...",
  "ip_address": "209.222.115.11",
  "icmp": true,
  "online": true,
  "stale": false,
  "error": null,
  "checked_at": "2026-09-12T15:59:36.430Z",
  "version": { "name": "Requires MC 1.8 / 1.21", "protocol": 47 },
  "players": { "online": 52184, "max": 200000, "sample": [] },
  "motd": {
    "raw": "§aHypixel Network",
    "clean": "Hypixel Network",
    "html": "<span style=\"color:#55FF55\">Hypixel Network</span>",
    "raw_lines": ["§aHypixel Network"],
    "clean_lines": ["Hypixel Network"]
  },
  "favicon": "data:image/png;base64,...",
  "srvRecord": null,
  "roundTripLatency": 18
}

GET/api/v1/trends

Servidores en tendencia

Devuelve servidores ordenados por puntuación de tendencia con paginación por cursor.

application/json

Autenticación

No requiere clave de API

Caché

5 min

Content-Type

application/json

Parámetros

Parámetro	Ubicación	Tipo	Predeterminado	Descripción
`limit`	query	integer	10	Tamaño de página limitado entre 1 y 50.
`cursor`	query	UUID	—	El valor meta.nextCursor de la respuesta anterior.

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/trends?limit=10"

Respuesta de ejemplo

json

{
  "success": true,
  "data": [
    {
      "server_id": "f17d4f75-...",
      "hostname": "mc.hypixel.net",
      "address": "mc.hypixel.net",
      "port": 25565,
      "edition": "java",
      "trend_score": 842,
      "daily_growth": 14.6,
      "is_online": true,
      "stale": false,
      "checked_at": "2026-09-12T15:59:36.430Z",
      "players_online": 52184,
      "players_max": 200000,
      "version": "Requires MC 1.8 / 1.21",
      "favicon": "21aa8597...",
      "record_players": 74312,
      "uptime_percentage": 99.8
    }
  ],
  "meta": { "nextCursor": "f17d4f75-...", "hasNext": true, "limit": 10 }
}

GET/api/v1/stats

Estadísticas globales

Proporciona totales de solicitudes, servidores comprobados, tasa online, jugadores activos y comprobaciones recientes.

application/json

Autenticación

No requiere clave de API

Caché

60 sec

Content-Type

application/json

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/stats"

Respuesta de ejemplo

json

{
  "totalRequests": 1284502,
  "apiRequests": 612340,
  "serverQueries": 672162,
  "totalChecks": 672162,
  "onlineServers": 428,
  "offlineServers": 91,
  "activePlayers": 184205,
  "recentChecks": [],
  "onlineRate": 82.5
}

GET/api/v1/icon/dynamic

Icono del servidor

Devuelve el favicon del servidor o la imagen predeterminada de MCAPI.TR si no está disponible.

image/png | image/webp

Autenticación

No requiere clave de API

Caché

Navegador 1 día, CDN 7 días

Content-Type

image/png | image/webp

Parámetros

Parámetro	Ubicación	Tipo	Predeterminado	Descripción
`address`*	query	string	—	Dirección del servidor. server se acepta como alias compatible.
`size`	query	integer	80	Tamaño WebP entre 16 y 256 píxeles.
`format`	query	png \| webp	png	Produce una imagen cuadrada optimizada al usar webp.

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/icon/dynamic?address=mc.hypixel.net&size=128&format=webp" --output server.webp

GET/api/v1/icon/sharp

Icono redondeado

Produce un icono PNG redimensionado con esquinas redondeadas.

image/png

Autenticación

No requiere clave de API

Caché

Navegador 1 día, CDN 7 días

Content-Type

image/png

Parámetros

Parámetro	Ubicación	Tipo	Predeterminado	Descripción
`address`*	query	string	—	Hostname o dirección IP del servidor.
`size`	query	integer	128	Tamaño de salida entre 32 y 512 píxeles.

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/icon/sharp?address=mc.hypixel.net&size=256" --output icon.png

GET/api/v1/banner/:address

Banner de estado

Crea un banner PNG compartible con nombre, jugadores, MOTD, ping y favicon.

image/png

Autenticación

No requiere clave de API

Caché

Según la política del servidor/CDN

Content-Type

image/png

Parámetros

Parámetro	Ubicación	Tipo	Predeterminado	Descripción
`address`*	path	string	—	Servidor usado para generar el banner.
`size`	query	small \| normal \| large	normal	Dimensiones: 400×130, 600×180 u 800×240.
`style`	query	modern \| classic	modern	Apariencia del banner.
`textColor`	query	hex color	#FFFFFF	Color principal del texto.
`accentColor`	query	hex color	#10B981	Color de acento del número de jugadores.
`showFavicon / showMotd / showPing`	query	boolean	true	Activa o desactiva icono, MOTD y latencia por separado.
`borderRadius`	query	number	0.5	Multiplicador del radio de esquina.

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/banner/mc.hypixel.net?size=large&accentColor=%2310B981" --output banner.png

GET/api/v1/banner/motd

Banner de texto MOTD

Convierte texto MOTD con formato Minecraft en un PNG de 800×180 sin consultar un servidor.

image/png

Autenticación

No requiere clave de API

Caché

Sin caché de aplicación

Content-Type

image/png

Parámetros

Parámetro	Ubicación	Tipo	Predeterminado	Descripción
`motd`*	query	string	—	Texto MOTD de hasta 300 caracteres.
`textColor`	query	hex color	#FFFFFF	Color de texto predeterminado.
`accentColor`	query	hex color	#10B981	Color de acento del fondo.

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/banner/motd?motd=%C2%A7aWelcome" --output motd.png

GET/api/v1/widget/:size/:address

Widget HTML integrable

Devuelve HTML personalizable con estado en vivo para sitios web y paneles.

text/html

Autenticación

No requiere clave de API

Caché

60 sec + stale-while-revalidate

Content-Type

text/html

Parámetros

Parámetro	Ubicación	Tipo	Predeterminado	Descripción
`size`*	path	small \| normal \| large	—	Diseño y altura predeterminada del widget.
`address`*	path	string	—	Dirección del servidor; se puede usar demo para previsualizar.
`theme`	query	dark \| light	dark	Tema de color base.
`showPlayers / showVersion / showMotd`	query	boolean	true	Activa o desactiva los campos principales por separado.
`showLatency / showFavicon`	query	boolean	true	Controla la visibilidad de ping y favicon.
`showProtocol / showBorder`	query	boolean	false	Muestra opcionalmente protocolo y borde.
`bgColor / textColor`	query	hex color	—	Colores de fondo y texto del widget.
`onlineColor / offlineColor`	query	hex color	#10b981 / #ef4444	Colores de estado online y offline.
`gradientBg / gradientFrom / gradientTo`	query	boolean / hex	false	Controles del fondo degradado.
`statusIndicator`	query	dot \| text \| badge \| none	dot	Estilo del indicador de estado.
`iconSize`	query	small \| medium \| large	medium	Tamaño del favicon.
`font`	query	Inter \| Roboto \| Poppins \| Montserrat \| Outfit	—	Familia de Google Fonts.
`textAlign`	query	left \| center \| right	left	Alineación del texto.
`customHeight`	query	CSS px	—	Altura personalizada entre 50 y 600 píxeles.
`borderRadius / borderWidth`	query	number	0.75 / 1	Medidas de esquinas y borde.
`hoverEffect / glowEffect / boxShadow`	query	boolean	false	Activa efectos visuales.
`playerBarStyle`	query	default \| gradient \| striped \| animated	default	Apariencia de la barra de ocupación.

Solicitud de ejemplo

bash

curl "https://mcapi.tr/api/v1/widget/normal/mc.hypixel.net?theme=dark&showFavicon=true"

04 — Esquema

Campos de respuesta del servidor

Campo	Tipo	Descripción
`query`	object	Host, puerto y modo de consulta resueltos.
`server_id`	UUID	Identificador estable del servidor en MCAPI.TR.
`online`	boolean	Indica si el ping de Minecraft se completó correctamente.
`stale`	boolean	Indica si la respuesta procede de la última consulta correcta en vez de un ping reciente.
`checked_at`	ISO 8601	Marca de tiempo UTC de la comprobación representada en esta respuesta.
`icmp`	boolean	Resultado de accesibilidad ICMP de la IP de destino.
`version`	object \| null	Nombre de versión y número de protocolo.
`players`	object \| null	Jugadores online, capacidad y muestra opcional.
`motd`	object \| null	Formatos MOTD original, limpio y HTML con listas de líneas.
`favicon`	data URL \| null	Favicon del servidor codificado en Base64.
`srvRecord`	object \| null	Detalles del registro SRV de Minecraft resuelto cuando se usó el descubrimiento.
`roundTripLatency`	number \| null	Latencia de consulta en milisegundos.
`error`	string \| null	Resumen seguro del error de una consulta fallida.

HTTP

Códigos de estado

200Solicitud correcta.

400Dirección o parámetros no válidos.

404Servidor offline o no accesible.

429Límite de solicitudes por minuto superado.

500Error inesperado del servidor.

503Modo de mantenimiento activo.

Políticas

Límites y caché

status:120 solicitudes por minuto y por IP.
default:300 solicitudes por minuto por defecto para endpoints generales.
media:Hasta 5.000 solicitudes por minuto para iconos, banners y widgets.
cors:Los endpoints públicos permiten todos los orígenes del navegador.
privacy:El perfilado de solicitudes no conserva IP sin procesar ni agentes de usuario.

SDK oficiales

Usa la API con Node.js y Python

Los clientes oficiales sin dependencias ofrecen consultas tipadas, descubrimiento, estadísticas y utilidades multimedia sin clave de API.

Node.js

mcapitr

npm ↗

Cliente Node.js basado en Promesas con declaraciones TypeScript completas y utilidades Buffer para medios generados.

bash

npm install mcapitr

Node.js 18+TypeScriptPromise API

Python

mcapitr

PyPI ↗

Clientes Python síncrono y asíncrono con excepciones tipadas, paginación y descargas de bytes.

bash

pip install mcapitr

Python 3.9+TypedSync + Async

Obtén tu primera respuesta en segundos

Envía una solicitud en vivo desde tu navegador

Todos los endpoints públicos

Estado de la API

Solicitud de ejemplo

Respuesta de ejemplo

Estado del servidor Minecraft

Parámetros

Solicitud de ejemplo

Respuesta de ejemplo

Servidores en tendencia

Parámetros

Solicitud de ejemplo

Respuesta de ejemplo

Estadísticas globales

Solicitud de ejemplo

Respuesta de ejemplo

Icono del servidor

Parámetros

Solicitud de ejemplo

Icono redondeado

Parámetros

Solicitud de ejemplo

Banner de estado

Parámetros

Solicitud de ejemplo

Banner de texto MOTD

Parámetros

Solicitud de ejemplo

Widget HTML integrable

Parámetros

Solicitud de ejemplo

Campos de respuesta del servidor

Códigos de estado

Límites y caché

Usa la API con Node.js y Python

mcapitr

mcapitr

Política de Privacidad

Protección de Sus Datos Personales

Datos Recopilados

Cookies

Seguridad de Datos

Contacto

Términos de Uso

Términos del Servicio

Definición del Servicio

Limitaciones de Uso

Descargo de Responsabilidad

Derechos de Propiedad Intelectual

Cambios

Contacto