{ "openapi": "3.1.0", "info": { "title": "MESU generation API", "version": "0.1.0", "description": "Local beta. Per-model validation is authoritative. API keys have a lifetime MESU credit limit; confirmed refunds/releases restore allowance. Credits and provider USD charges are distinct. Do not resubmit uncertain tasks." }, "servers": [ { "url": "/api/mesu/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/models": { "get": { "summary": "Read the shared model capability catalog", "responses": { "400": { "description": "Invalid request or unsupported model options", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Invalid, expired or revoked key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient account credits or key lifetime limit", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Scope or account status forbids access", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Owned record not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflicting/active task", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "60 requests per minute per key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Generation worker unavailable or paused", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/jobs": { "post": { "summary": "Submit paid generation; reserve credits atomically for a serial batch", "responses": { "400": { "description": "Invalid request or unsupported model options", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Invalid, expired or revoked key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient account credits or key lifetime limit", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Scope or account status forbids access", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Owned record not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflicting/active task", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "60 requests per minute per key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Generation worker unavailable or paused", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "submitted", "uncertain", "completed", "failed", "cancelled" ] }, "params": { "type": "string", "description": "JSON encoded normalized parameters" }, "metadata": { "type": [ "string", "null" ], "description": "JSON encoded measured media properties, when available" }, "media_url": { "type": [ "string", "null" ] }, "billing": { "type": [ "string", "null" ], "description": "Provider billing JSON, when available" }, "credit_cost": { "type": "integer" } } }, "batchId": { "type": [ "string", "null" ] }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "submitted", "uncertain", "completed", "failed", "cancelled" ] }, "params": { "type": "string", "description": "JSON encoded normalized parameters" }, "metadata": { "type": [ "string", "null" ], "description": "JSON encoded measured media properties, when available" }, "media_url": { "type": [ "string", "null" ] }, "billing": { "type": [ "string", "null" ], "description": "Provider billing JSON, when available" }, "credit_cost": { "type": "integer" } } } } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "submitted", "uncertain", "completed", "failed", "cancelled" ] }, "params": { "type": "string", "description": "JSON encoded normalized parameters" }, "metadata": { "type": [ "string", "null" ], "description": "JSON encoded measured media properties, when available" }, "media_url": { "type": [ "string", "null" ] }, "billing": { "type": [ "string", "null" ], "description": "Provider billing JSON, when available" }, "credit_cost": { "type": "integer" } } }, "batchId": { "type": [ "string", "null" ] }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "submitted", "uncertain", "completed", "failed", "cancelled" ] }, "params": { "type": "string", "description": "JSON encoded normalized parameters" }, "metadata": { "type": [ "string", "null" ], "description": "JSON encoded measured media properties, when available" }, "media_url": { "type": [ "string", "null" ] }, "billing": { "type": [ "string", "null" ], "description": "Provider billing JSON, when available" }, "credit_cost": { "type": "integer" } } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } } }, "get": { "summary": "List own tasks", "responses": { "400": { "description": "Invalid request or unsupported model options", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Invalid, expired or revoked key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient account credits or key lifetime limit", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Scope or account status forbids access", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Owned record not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflicting/active task", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "60 requests per minute per key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Generation worker unavailable or paused", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "submitted", "uncertain", "completed", "failed", "cancelled" ] }, "params": { "type": "string", "description": "JSON encoded normalized parameters" }, "metadata": { "type": [ "string", "null" ], "description": "JSON encoded measured media properties, when available" }, "media_url": { "type": [ "string", "null" ] }, "billing": { "type": [ "string", "null" ], "description": "Provider billing JSON, when available" }, "credit_cost": { "type": "integer" } } } }, "nextCursor": { "type": [ "string", "null" ] } } } } } } }, "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string" } } ] } }, "/jobs/{id}": { "get": { "summary": "Read an owned task and its related generations", "responses": { "400": { "description": "Invalid request or unsupported model options", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Invalid, expired or revoked key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient account credits or key lifetime limit", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Scope or account status forbids access", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Owned record not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflicting/active task", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "60 requests per minute per key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Generation worker unavailable or paused", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "submitted", "uncertain", "completed", "failed", "cancelled" ] }, "params": { "type": "string", "description": "JSON encoded normalized parameters" }, "metadata": { "type": [ "string", "null" ], "description": "JSON encoded measured media properties, when available" }, "media_url": { "type": [ "string", "null" ] }, "billing": { "type": [ "string", "null" ], "description": "Provider billing JSON, when available" }, "credit_cost": { "type": "integer" } } }, "batchId": { "type": [ "string", "null" ] }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "submitted", "uncertain", "completed", "failed", "cancelled" ] }, "params": { "type": "string", "description": "JSON encoded normalized parameters" }, "metadata": { "type": [ "string", "null" ], "description": "JSON encoded measured media properties, when available" }, "media_url": { "type": [ "string", "null" ] }, "billing": { "type": [ "string", "null" ], "description": "Provider billing JSON, when available" }, "credit_cost": { "type": "integer" } } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/jobs/{id}/media": { "get": { "summary": "Read original media; Range supported", "responses": { "400": { "description": "Invalid request or unsupported model options", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Invalid, expired or revoked key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient account credits or key lifetime limit", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Scope or account status forbids access", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Owned record not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflicting/active task", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "60 requests per minute per key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Generation worker unavailable or paused", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "200": { "description": "Original media", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial content" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "example": "bytes=0-1023" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "MESU API key" } }, "schemas": { "Generation": { "type": "object", "required": [ "requestKey", "kind", "model", "prompt", "ratio", "resolution" ], "properties": { "requestKey": { "type": "string", "pattern": "^[a-zA-Z0-9-]{16,80}$", "description": "Persist before submitting. Reuse only to recover the identical submission." }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "model": { "type": "string", "description": "Verified exact ID and capabilities from GET /models." }, "prompt": { "type": "string", "maxLength": 20000 }, "count": { "type": "integer", "enum": [ 1, 2, 4 ], "default": 1 }, "ratio": { "type": "string" }, "resolution": { "type": "string" }, "duration": { "type": "integer" }, "mode": { "type": "string", "enum": [ "text", "image", "frames", "reference", "edit", "video-edit", "extend", "draft", "final" ] }, "seed": { "type": [ "integer", "null" ] }, "audioPrompt": { "type": "string" }, "negativePrompt": { "type": "string" }, "transparent": { "type": "boolean" }, "draftJobId": { "type": "string", "format": "uuid" }, "references": { "type": "array", "items": { "type": "object", "required": [ "id", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio", "source_video" ] } } } }, "generateAudio": { "type": "boolean" }, "outputFormat": { "type": "string" }, "quality": { "type": "string" }, "shotType": { "type": "string" }, "promptExtend": { "type": "boolean" }, "mentions": { "type": "array", "items": { "type": "object", "required": [ "token", "assetId" ], "properties": { "token": { "type": "string", "description": "Stable @imageN/@videoN/@audioN token" }, "assetId": { "type": "string", "format": "uuid" } } } } } } } } }