Docs
Render osu!mania replays from your bot or your tooling.
Four steps, and only the first one writes anything. A bot that follows them needs nothing else.
You send the replay
POST /renders with the .osr as multipart. It answers 202 with an id before the render starts.
You wait
Register a callbackUrl and Miru calls you when it is done, or poll GET /renders/:id every few seconds.
You read the result
status turns COMPLETED and output carries the video URL, which expires: download it or keep your own copy.
If it went wrong
status turns FAILED with an error object. Anything still queued is cancelled with DELETE /renders/:id.
Create a key in your account settings and send it in the header. It is shown only once.
Authorization: Bearer mk_live_...Upload an .osr and poll until it is done.
/api/v1/rendersCrear 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`.
/api/v1/rendersListar tus renders
Paginado por cursor: pasa el `nextCursor` de la respuesta anterior.
/api/v1/renders/{id}Estado de un render
/api/v1/renders/{id}Cancelar un render
Solo si sigue en cola o procesando.
/api/v1/quotaCuánto te queda
No consume cuota. Sirve para que un bot se autorregule.
/api/v1/skinsTus skins
Los ids que acepta `skinId` al crear un render. Solo las ya procesadas.
/api/v1/presetsTus presets
Los ids que acepta `presetId` al crear un render.
/api/v1/statusEstado de la cola
Público: no necesita key.
The full spec, to generate clients or import into Postman: openapi.json
What every endpoint returns inside data. Fields that stay null until the render reaches their stage are still there as null, they do not disappear.
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) |
QUEUED and PROCESSING are the ones that keep moving. The other three are final: a render never leaves them.
QUEUEDPROCESSINGCOMPLETEDFAILEDCANCELLEDSend Idempotency-Key and a network retry will not create two renders: the second call returns the same one, with 200 instead of 202.
Instead of polling, register a callbackUrl when you create the render and we will tell you when it is done.
Every delivery is signed with HMAC-SHA256 in X-Miru-Signature, using your key secret. Without verifying it, anyone who knows your URL can send you a fake notification.
Five retries within an hour if your server does not answer. X-Miru-Delivery carries a unique id so you can drop duplicates.
Per key and per hour, on free accounts only. They ride in the headers of every response so your bot can stop before the 429; with Plus there is no cap and those headers are not sent.
| Plan | Renders per hour | Concurrent | Resolution | Webhooks |
|---|---|---|---|---|
| Free | 10 | 1 | 720p60 | No |
| Plus | No cap | No cap | 1080p60 | Yes |
Always the same shape. Compare against code, which is stable; the message can change.
| Code | HTTP | When |
|---|---|---|
UNAUTHORIZED | 401 | The key is missing, malformed or revoked. |
FORBIDDEN | 403 | The key is valid but your plan does not allow that. |
NOT_FOUND | 404 | That render does not exist, or is not yours. |
VALIDATION_ERROR | 400 | Something in the request does not match what the endpoint takes. |
RATE_LIMITED | 429 | You ran out of renders for the hour. Retry-After says how long. |
ACTIVE_RENDER_LIMIT | 403 | You already have as many renders going at once as your plan allows. |
CONFLICT | 409 | The render had already finished, so there is nothing to cancel. |