Documentacion

API de Miru

Renderiza replays de osu!mania desde tu bot o tu herramienta.

Crear una API key

Cómo transcurre un render

Cuatro pasos, y solo el primero escribe algo. Un bot que los siga no necesita nada más.

1
Mandas el replay
POST /renders con el .osr como multipart. Contesta 202 con un id antes de empezar a renderizar.
2
Esperas
Registra una callbackUrl y Miru te avisa al terminar, o consulta GET /renders/:id cada unos segundos.
3
Lees el resultado
status pasa a COMPLETED y output trae la URL del video, que vence: descárgalo o guarda tu propia copia.
4
Si salió mal
status pasa a FAILED con un objeto error. Lo que siga en cola se cancela con DELETE /renders/:id.

Autenticación

Crea una key desde los ajustes de tu cuenta y mándala en la cabecera. Se muestra una sola vez.

Authorization: Bearer mk_live_...

Empezar

Sube un .osr y consulta el estado hasta que termine.

Endpoints

post/api/v1/renders

Crear un render

Se manda el `.osr` como multipart en el campo `replay`. Manda `Idempotency-Key` si quieres que un reintento de red no genere dos renders: con la misma clave, la segunda llamada devuelve el mismo render con `200` en vez de `202`.

get/api/v1/renders

Listar tus renders

Paginado por cursor: pasa el `nextCursor` de la respuesta anterior.

get/api/v1/renders/{id}

Estado de un render

delete/api/v1/renders/{id}

Cancelar un render

Solo si sigue en cola o procesando.

get/api/v1/quota

Cuánto te queda

No consume cuota. Sirve para que un bot se autorregule.

get/api/v1/skins

Tus skins

Los ids que acepta `skinId` al crear un render. Solo las ya procesadas.

get/api/v1/presets

Tus presets

Los ids que acepta `presetId` al crear un render.

get/api/v1/status

Estado de la cola

Público: no necesita key.

La spec completa, para generar clientes o importar en Postman: openapi.json

El objeto render

Lo que devuelve cada endpoint dentro de data. Los campos que son null hasta que el render llega a su etapa siguen ahí en null, no desaparecen.

data

`id`	`string (uuid)`
`status`	`"QUEUED" \| "PROCESSING" \| "COMPLETED" \| "FAILED" \| "CANCELLED"`
`progress`	`integer`
`phase`	`stringnull`
`resolution`	`"720p60" \| "1080p60"`
`beatmap`	`object`
`output`	`objectnull`	Solo cuando el render terminó. La URL vence.
`error`	`objectnull`
`createdAt`	`string (date-time)`
`startedAt`	`string,null (date-time)`
`completedAt`	`string,null (date-time)`

Los estados por los que pasa

QUEUED y PROCESSING son los que siguen moviéndose. Los otros tres son finales: de ahí un render no sale.

QUEUEDPROCESSINGCOMPLETEDFAILEDCANCELLED

Idempotencia

Manda Idempotency-Key y un reintento de red no te va a generar dos renders: la segunda llamada devuelve el mismo, con 200 en vez de 202.

Webhooks

En vez de consultar en bucle, registra una callbackUrl al crear el render y te avisamos cuando termina.

Verifica la firma, siempre

Cada entrega va firmada con HMAC-SHA256 en X-Miru-Signature, usando el secreto de tu key. Sin verificarla, cualquiera que conozca tu URL puede mandarte un aviso falso.

Reintentos

Cinco reintentos en menos de una hora si tu servidor no responde. X-Miru-Delivery trae un id unico para que puedas descartar duplicados.

Límites

Por key y por hora, solo en las cuentas gratis. Van en las cabeceras de cada respuesta, asi tu bot puede frenar antes del 429; con Plus no hay tope y esas cabeceras no vienen.

Plan	Renders por hora	Simultaneos	Resolucion	Webhooks
Free	10	1	720p60	No
Plus	Sin tope	Sin tope	1080p60	Si

Errores

Siempre la misma forma. Compara contra code, que es estable; el mensaje puede cambiar.

Codigo	HTTP	Cuando
`UNAUTHORIZED`	401	Falta la key, está mal formada o fue revocada.
`FORBIDDEN`	403	La key es válida pero tu plan no permite eso.
`NOT_FOUND`	404	Ese render no existe, o no es tuyo.
`VALIDATION_ERROR`	400	Algo del pedido no coincide con lo que el endpoint acepta.
`RATE_LIMITED`	429	Se te acabaron los renders de la hora. Retry-After dice cuánto falta.
`ACTIVE_RENDER_LIMIT`	403	Ya tienes tantos renders a la vez como permite tu plan.
`CONFLICT`	409	El render ya había terminado, así que no hay nada que cancelar.