{ "openapi": "3.1.0", "info": { "title": "Lumeta API", "version": "1.0.0", "summary": "Same Lumeta account, same models, same credits, same shelves and projects, from code.", "description": "Authenticate with `Authorization: Bearer lm_live_...` (keys: https://lumeta.ai/account/developer/, paid plans). Every response carries `X-Request-Id`; every error is `{\"error\": {\"code\", \"message\", \"param\"?, \"request_id\"}}`. Public ids: `gen_`, `file_`, `shelf_`, `proj_`, `voice_`. Media inputs take references, never filenames: `file_`, `shelf_`, `shelf:`, `gen_#`, `voice_`, or an `https://` URL. Limits per credential: 300 requests/min, 20 generations/min, 60 estimates/min. Guide, examples and webhook signatures: https://lumeta.ai/developers/docs/", "contact": { "url": "https://lumeta.ai/developers/" } }, "servers": [ { "url": "https://api.lumeta.ai" } ], "security": [ { "bearer": [] } ], "paths": { "/": { "get": { "operationId": "root", "summary": "The API root: where the docs and the OpenAPI document are.", "security": [], "x-lumeta-scope": null, "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/openapi.json": { "get": { "operationId": "openapi", "summary": "OpenAPI 3.1 description of this API.", "security": [], "x-lumeta-scope": null, "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "protected_resource_metadata", "summary": "RFC 9728 protected-resource metadata.", "security": [], "x-lumeta-scope": null, "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-protected-resource/mcp": { "get": { "operationId": "protected_resource_metadata", "summary": "RFC 9728 protected-resource metadata (MCP resource).", "security": [], "x-lumeta-scope": null, "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/models": { "get": { "operationId": "models_list", "summary": "List the models you can run. Filters: type=image|video|audio, q=, task= (adds a recommendation).", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "image | video | audio | other" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Text to match in name, slug, description or categories." }, { "name": "task", "in": "query", "required": false, "schema": { "type": "string" }, "description": "What you want to make; adds `recommended`." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "recommended": { "type": "object" }, "defaults": { "type": "object", "description": "image, video, audio: the model this account opens with on the web for that kind ({id, slug, name, base_credits}, or null). Run it when only a kind is named." } } } } } } } } }, "/v1/models/{model}": { "get": { "operationId": "model_get", "summary": "One model with its input schema.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model id (e.g. 47) or English slug (e.g. gpt-image-2)." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } } } } }, "/v1/models/{model}/schema": { "get": { "operationId": "model_schema", "summary": "The JSON Schema of a model's input object.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model id (e.g. 47) or English slug (e.g. gpt-image-2)." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "JSON Schema 2020-12" } } } } } } }, "/v1/estimate": { "post": { "operationId": "estimate", "summary": "Price a generation without running it: exactly what POST /v1/generations would charge for this body.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Estimate" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model id or slug." }, "input": { "type": "object", "description": "The model's inputs; schema at GET /v1/models/{model}/schema." }, "project": { "type": "string", "description": "`proj_` to file the generation in (default: your current project)." } } } } } } } }, "/v1/generations": { "post": { "operationId": "generations_create", "summary": "Start a generation. Spends credits. 202 while it runs (poll GET /v1/generations/{id}?wait=45), 200 when the tool answers synchronously. Supports Idempotency-Key.", "security": [ { "bearer": [ "generate" ] } ], "x-lumeta-scope": "generate", "responses": { "default": { "$ref": "#/components/responses/Error" }, "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model id or slug." }, "input": { "type": "object", "description": "The model's inputs; schema at GET /v1/models/{model}/schema." }, "project": { "type": "string", "description": "`proj_` to file the generation in (default: your current project)." } } } } } } }, "get": { "operationId": "generations_list", "summary": "Your generations, newest first. Filters: status, model, project, origin=web|api|mcp|cli; cursor paging.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "queued | processing | succeeded | failed" }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Model id or slug." }, { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`proj_`: every member's generations in that project." }, { "name": "origin", "in": "query", "required": false, "schema": { "type": "string" }, "description": "web | api | mcp | cli" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page size, 1-100 (default 20)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Generation" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/generations/{id}": { "get": { "operationId": "generation_get", "summary": "One generation. ?wait= holds the request until it finishes or the time is up.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." }, { "name": "wait", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 45 }, "description": "Seconds to hold the request until the generation finishes (max 45)." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } } } } }, "/v1/generations/{id}/cancel": { "post": { "operationId": "generation_cancel", "summary": "Stop a generation that has not finished, and refund it. Only where its provider can really stop it (today: models that run on Replicate); otherwise 409 not_cancelable and it finishes on its own.", "security": [ { "bearer": [ "generate" ] } ], "x-lumeta-scope": "generate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } } } } }, "/v1/files": { "post": { "operationId": "files_create", "summary": "Upload a file (multipart/form-data, part \"file\"). Same validation, limits and normalization as the web uploader.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "responses": { "default": { "$ref": "#/components/responses/Error" }, "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "model": { "type": "string", "description": "Optional: the model this file is for (id or slug); per-model upload limits apply." } } } } } } }, "get": { "operationId": "files_list", "summary": "Your uploads and imports from the last 60 days. Filters: type, project; cursor paging.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "image | video | audio | other" }, { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`proj_`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page size, 1-100 (default 20)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/files/import": { "post": { "operationId": "files_import", "summary": "Import a public https:// URL as one of your files.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "responses": { "default": { "$ref": "#/components/responses/Error" }, "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "model": { "type": "string" } } } } } } } }, "/v1/files/{id}": { "get": { "operationId": "file_get", "summary": "One file.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } } } } }, "/v1/shelves": { "get": { "operationId": "shelves_list", "summary": "Your shelves: proj_0 (All Projects) and one per project, with item counts.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shelf" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/shelves/{project}/items": { "get": { "operationId": "shelf_items_list", "summary": "Items on a shelf, by the names you gave them. Filters: q=, type; cursor paging.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`proj_`; `proj_0` is the All Projects shelf." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match the item name (or filename)." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "image | video | audio | other" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page size, 1-100 (default 20)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShelfItem" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } }, "post": { "operationId": "shelf_item_create", "summary": "Pin a generation output (gen_#) or a file (file_) to a shelf with a name.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`proj_`; `proj_0` is the All Projects shelf." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShelfItem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "media" ], "properties": { "media": { "type": "string", "description": "`gen_#` or `file_`" }, "name": { "type": "string", "maxLength": 120 } } } } } } } }, "/v1/shelves/{project}/items/{id}": { "patch": { "operationId": "shelf_item_update", "summary": "Rename a shelf item.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`proj_`; `proj_0` is the All Projects shelf." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShelfItem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 } } } } } } }, "delete": { "operationId": "shelf_item_delete", "summary": "Remove an item from a shelf (the file stays).", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`proj_`; `proj_0` is the All Projects shelf." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } } }, "/v1/projects": { "get": { "operationId": "projects_list", "summary": "Your projects, including ones shared with you.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } }, "post": { "operationId": "projects_create", "summary": "Create a project. It becomes your current project, as on the web.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "responses": { "default": { "$ref": "#/components/responses/Error" }, "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "default_aspect_ratio": { "type": "string", "examples": [ "16:9" ] } } } } } } } }, "/v1/voices": { "get": { "operationId": "voices_list", "summary": "Your own cloned/trained voices; each carries the value a voice input accepts.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" }, "description": "rvc | inworld | elevenlabs" } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/account": { "get": { "operationId": "account_get", "summary": "Plan, credits and this credential's scopes, caps and spend.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } } } } }, "/v1/webhook-endpoints": { "get": { "operationId": "webhook_endpoints_list", "summary": "Your webhook endpoints (up to 5).", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } }, "post": { "operationId": "webhook_endpoint_create", "summary": "Register an https:// URL for generation.succeeded / generation.failed events. The signing secret is in this response only.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "responses": { "default": { "$ref": "#/components/responses/Error" }, "201": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "whsec_...: signs every event to this endpoint. Returned here only." }, "secret_note": { "type": "string" } } } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "https:// on port 443, resolving to a public address." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "generation.succeeded", "generation.failed" ] }, "description": "[\"*\"] (the default) for every event." }, "enabled": { "type": "boolean", "description": "PATCH only. true also clears the failure count." } } } } } } } }, "/v1/webhook-endpoints/{id}": { "get": { "operationId": "webhook_endpoint_get", "summary": "One webhook endpoint, with its delivery health.", "security": [ { "bearer": [ "read" ] } ], "x-lumeta-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "patch": { "operationId": "webhook_endpoint_update", "summary": "Change url, events or enabled. Turning it back on clears the failure count.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "url": { "type": "string", "format": "uri", "description": "https:// on port 443, resolving to a public address." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "generation.succeeded", "generation.failed" ] }, "description": "[\"*\"] (the default) for every event." }, "enabled": { "type": "boolean", "description": "PATCH only. true also clears the failure count." } } } } } } }, "delete": { "operationId": "webhook_endpoint_delete", "summary": "Delete a webhook endpoint and its queued events.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } } }, "/v1/webhook-endpoints/{id}/test": { "post": { "operationId": "webhook_endpoint_test", "summary": "Send a signed webhook.test event now and report what the receiver answered.", "security": [ { "bearer": [ "library" ] } ], "x-lumeta-scope": "library", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public id (`gen_`, `file_`, `shelf_`, `hook_`) or its number." } ], "responses": { "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string" }, "delivered": { "type": "boolean" }, "status": { "type": [ "integer", "null" ], "description": "The receiver's HTTP status; null when it did not answer." }, "error": { "type": [ "string", "null" ] }, "duration_ms": { "type": "integer" } } } } } } } } } }, "webhooks": { "generation.succeeded": { "post": { "operationId": "generation_succeeded", "summary": "A generation finished with its outputs.", "description": "POSTed as JSON to every endpoint registered with POST /v1/webhook-endpoints, for every generation on the account (web, API, MCP, CLI; data.origin says which) started after the endpoint was created. Headers: Lumeta-Event-Id (evt_..., also body.id), Lumeta-Event-Type, `Lumeta-Signature: t=,v1=`, where the hex is the HMAC-SHA256 of `\".\"` keyed with the endpoint secret. Verify the signature over the raw bytes and refuse a t older than 5 minutes. Answer any 2xx within 5 seconds; anything else (a redirect, a timeout, a 4xx or 5xx) is retried after 1 min, 5 min, 30 min, 2 h and 12 h, with the same event id. An event goes out a few seconds after its generation finishes (within about a minute for one that ran longer than two hours), not necessarily in order; a retry carries the generation as it is then.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. The body is ignored (only the first 4 KB are read)." } } } }, "generation.failed": { "post": { "operationId": "generation_failed", "summary": "A generation failed (data.error says why; data.credits_charged is 0 when it was refunded).", "description": "POSTed as JSON to every endpoint registered with POST /v1/webhook-endpoints, for every generation on the account (web, API, MCP, CLI; data.origin says which) started after the endpoint was created. Headers: Lumeta-Event-Id (evt_..., also body.id), Lumeta-Event-Type, `Lumeta-Signature: t=,v1=`, where the hex is the HMAC-SHA256 of `\".\"` keyed with the endpoint secret. Verify the signature over the raw bytes and refuse a t older than 5 minutes. Answer any 2xx within 5 seconds; anything else (a redirect, a timeout, a 4xx or 5xx) is retried after 1 min, 5 min, 30 min, 2 h and 12 h, with the same event id. An event goes out a few seconds after its generation finishes (within about a minute for one that ran longer than two hours), not necessarily in order; a retry carries the generation as it is then.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. The body is ignored (only the first 4 KB are read)." } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A personal API key (lm_live_...) or an OAuth access token (lma_...). Scopes: read, generate, library." } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable: unauthorized, invalid_token, plan_required, insufficient_scope, not_found, invalid_input, invalid_json, moderation_blocked, project_read_only, token_cap_exceeded, insufficient_credits, concurrency_limit, rate_limited, idempotency_conflict, idempotency_in_progress, already_exists, not_cancelable, model_unavailable, provider_error, service_unavailable, internal_error." }, "message": { "type": "string" }, "param": { "type": "string", "description": "The input field or parameter at fault, when there is one." }, "request_id": { "type": "string" } } } } }, "Model": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "other" ] }, "description": { "type": "string" }, "long_description": { "type": [ "string", "null" ] }, "min_plan": { "type": "integer", "description": "1 Free, 2 Pro, 3 Ultimate" }, "min_plan_name": { "type": "string" }, "base_credits": { "type": "number", "description": "Base price; POST /v1/estimate gives the exact figure for an input." }, "edits_media": { "type": "boolean", "description": "Takes an image/video/audio in and edits it." }, "categories": { "type": "array", "items": { "type": "string" } }, "schema_url": { "type": "string" }, "schema_hash": { "type": "string", "description": "Changes when the input schema changes." }, "input_schema": { "type": "object", "description": "JSON Schema 2020-12 of `input` (GET /v1/models/{model} only)." }, "compat": { "type": "object", "description": "Other APIs' names for this model, on models that have one: {\"higgsfield\": [paths]} are the Higgsfield API paths that run it at https://api.lumeta.ai/higgsfield.", "properties": { "higgsfield": { "type": "array", "items": { "type": "string" } } } } } }, "Estimate": { "type": "object", "properties": { "credits": { "type": "integer" }, "credits_remaining": { "type": "integer" }, "cap_remaining": { "type": [ "integer", "null" ] }, "enough": { "type": "boolean", "description": "Whether POST /v1/generations would be accepted right now." } } }, "Generation": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed" ] }, "model": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "project": { "type": [ "string", "null" ] }, "input": { "type": "object" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "other" ] }, "url": { "type": "string", "description": "Durable https URL of the stored file." }, "mime": { "type": [ "string", "null" ] }, "width": { "type": "integer" }, "height": { "type": "integer" }, "duration": { "type": "number", "description": "Seconds, for audio and video." }, "size": { "type": "integer", "description": "Bytes." } } } }, "credits_charged": { "type": "integer", "description": "What was charged; a refunded failure reads 0." }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "description": "canceled when you canceled it; otherwise the error codes above." }, "message": { "type": "string" } } }, "origin": { "type": "string", "enum": [ "web", "api", "mcp", "cli" ] }, "request_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "completed_in_seconds": { "type": [ "number", "null" ] }, "credits_remaining": { "type": "integer", "description": "On POST /v1/generations only." }, "cap_remaining": { "type": [ "integer", "null" ] } } }, "File": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "source": { "type": "string" }, "project": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "other" ] }, "url": { "type": "string", "description": "Durable https URL of the stored file." }, "mime": { "type": [ "string", "null" ] }, "width": { "type": "integer" }, "height": { "type": "integer" }, "duration": { "type": "number", "description": "Seconds, for audio and video." }, "size": { "type": "integer", "description": "Bytes." } } }, "Shelf": { "type": "object", "properties": { "project": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "item_count": { "type": "integer" }, "items_url": { "type": "string" } } }, "ShelfItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "project": { "type": "string" }, "created_at": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "other" ] }, "url": { "type": "string", "description": "Durable https URL of the stored file." }, "width": { "type": "integer" }, "height": { "type": "integer" }, "duration": { "type": "number", "description": "Seconds, for audio and video." } } }, "Project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ] }, "default_aspect_ratio": { "type": [ "string", "null" ] }, "generation_count": { "type": [ "integer", "null" ] }, "current": { "type": "boolean" }, "created_at": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] } } }, "Voice": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "input_value": { "type": "string", "description": "What a model's voice input accepts for this voice (`voice_` works too)." }, "created_at": { "type": "string" } } }, "Account": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "integer" }, "plan_name": { "type": "string" }, "current_project": { "type": [ "string", "null" ] } } }, "credits": { "type": "object", "properties": { "remaining": { "type": "integer" }, "monthly_remaining": { "type": "integer" }, "purchased": { "type": "integer" }, "monthly_allowance": { "type": "integer" }, "cycle_refreshes_at": { "type": "string" } } }, "credential": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "credit_cap_daily": { "type": [ "integer", "null" ] }, "credit_cap_monthly": { "type": [ "integer", "null" ] }, "spent_today": { "type": "integer" }, "spent_this_month": { "type": "integer" }, "cap_remaining": { "type": [ "integer", "null" ] }, "allow_auto_topup": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ] } } }, "credits_remaining": { "type": "integer" }, "cap_remaining": { "type": [ "integer", "null" ] } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "`hook_`" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] or a list of generation.succeeded, generation.failed." }, "enabled": { "type": "boolean", "description": "false after you switch it off, or after an event failed every retry with no success in between." }, "failure_count": { "type": "integer", "description": "Failed attempts in a row; a 2xx resets it." }, "last_success_at": { "type": [ "string", "null" ] }, "last_failure_at": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "data" ], "properties": { "id": { "type": "string", "description": "evt_...: the same for every attempt and every endpoint of one event (also in Lumeta-Event-Id). Deduplicate on it." }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "generation.succeeded", "generation.failed", "webhook.test" ] }, "created_at": { "type": "string" }, "attempt": { "type": "integer", "description": "1 for the first delivery, then 2 to 6 for the retries." }, "data": { "description": "The generation as it is when this attempt is sent (GET /v1/generations/{id}). Act on data.status.", "oneOf": [ { "$ref": "#/components/schemas/Generation" }, { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_test" ] }, "endpoint": { "type": "string" }, "message": { "type": "string" } } } ] } } } } } }