{ "openapi": "3.1.0", "info": { "title": "MakerNice API", "version": "1", "description": "Video and image generation API. Amounts are in US dollars, as integer strings of micro-USD (1,000,000 = $1.00). Authenticate with `Authorization: Bearer mn-…`." }, "servers": [ { "url": "https://api.makernice.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/generations/quote": { "post": { "operationId": "createQuote", "summary": "Get a quote", "description": "Locks the price of a generation request for 12 minutes. A quote can be used for one generation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationInput" } } } }, "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Error: `invalid_request`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Error: `invalid_api_key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Error: `payload_too_large`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Error: `price_unavailable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Error: `rate_limited`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/generations": { "post": { "operationId": "createGeneration", "summary": "Create a generation", "description": "Holds the quoted amount and queues the generation. Repeating the request with the same Idempotency-Key returns the original generation (200).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1–200 printable ASCII characters, unique within your account", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGenerationBody" } } } }, "responses": { "200": { "description": "Replay of an earlier request with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "202": { "description": "Generation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "400": { "description": "Error: `invalid_request`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Error: `invalid_api_key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "Error: `insufficient_balance`, `key_spend_limit_reached`, `daily_spend_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Error: `org_frozen`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Error: `quote_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Error: `quote_already_used`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "Error: `quote_expired`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Error: `payload_too_large`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Error: `idempotency_conflict`, `quote_mismatch`, `content_rejected`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Error: `rate_limited`, `concurrency_limit_reached`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "operationId": "listGenerations", "summary": "List generations", "description": "Generations in your account, newest first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by output type", "schema": { "type": "string", "enum": [ "video", "image" ] } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated public statuses, e.g. `queued,generating`", "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "description": "Filter by model id", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Generation id (exact) or text contained in the prompt (case-insensitive)", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Only generations created at or after this ISO 8601 time (with offset), e.g. `2026-10-01T00:00:00Z`", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Only generations created before this ISO 8601 time (with offset)", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "Comma-separated API key ids (`key_…`); `web` selects generations created in the console without a key", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of generations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationList" } } } }, "400": { "description": "Error: `invalid_request`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Error: `invalid_api_key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Error: `rate_limited`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/generations/{id}": { "get": { "operationId": "getGeneration", "summary": "Get a generation", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Generation id (gen_…)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "401": { "description": "Error: `invalid_api_key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Error: `task_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Error: `rate_limited`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/generations/{id}/events": { "get": { "operationId": "getGenerationEvents", "summary": "Get a generation's timeline", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Generation id (gen_…)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeline" } } } }, "401": { "description": "Error: `invalid_api_key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Error: `task_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Error: `rate_limited`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/generations/{id}/outputs/{n}": { "get": { "operationId": "downloadOutput", "summary": "Download an output", "description": "Redirects (302) to a short-lived signed URL of the file. Only available once the generation has succeeded.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Generation id (gen_…)", "schema": { "type": "string" } }, { "name": "n", "in": "path", "required": true, "description": "Output index (`outputs[].index`)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "download", "in": "query", "required": false, "description": "Any non-empty value (e.g. `1`) asks for `Content-Disposition: attachment`. Ignored until the file has been stored (`state: stored`)", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the file", "headers": { "Location": { "description": "Signed URL of the file", "schema": { "type": "string" } } } }, "401": { "description": "Error: `invalid_api_key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Error: `task_not_found`, `output_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "Error: `output_expired`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Error: `rate_limited`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/generations/{id}/cancel": { "post": { "operationId": "cancelGeneration", "summary": "Cancel a generation", "description": "Only queued generations can be canceled; the hold is released in full.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Generation id (gen_…)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Canceled generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "401": { "description": "Error: `invalid_api_key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Error: `task_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Error: `not_cancelable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Error: `rate_limited`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/models": { "get": { "security": [], "operationId": "listModels", "summary": "List models", "description": "Models with their modes and current prices. Only priced modes are listed; a model-level resolution may still lack a price in a given mode (check `modes[].prices`; quoting it returns 422 price_unavailable). No API key required.", "responses": { "200": { "description": "Models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Models" } } } }, "429": { "description": "Error: `rate_limited`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/pricing": { "get": { "security": [], "operationId": "getPricing", "summary": "Get pricing", "description": "Unit prices of the current price version. No API key required.", "responses": { "200": { "description": "Pricing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Pricing" } } } }, "429": { "description": "Error: `rate_limited`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error: `internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "mn-…" } }, "schemas": { "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "prompt", "input_image", "model" ] }, "details": {}, "request_id": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "GenerationInput": { "type": "object", "properties": { "model": { "type": "string" }, "mode": { "type": "string", "enum": [ "t2v", "i2v", "flf", "r2v", "t2i", "i2i" ] }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "duration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "resolution": { "type": "string" }, "aspect_ratio": { "type": "string" }, "image_url": { "type": "string", "maxLength": 2048, "description": "https URL" }, "last_image_url": { "type": "string", "maxLength": 2048, "description": "https URL" }, "reference_images": { "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 2048, "description": "https URL" } }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "generate_audio": { "type": "boolean" }, "prompt_expansion": { "type": "string", "enum": [ "off", "balanced", "quality" ] }, "negative_prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "watermark": { "type": "boolean" } }, "required": [ "model", "mode", "prompt" ], "additionalProperties": false }, "CreateGenerationBody": { "type": "object", "properties": { "quote_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "input": { "$ref": "#/components/schemas/GenerationInput" }, "callback_url": { "type": "string", "maxLength": 2048, "pattern": "^https:\\/\\/", "description": "https URL without credentials (no user:pass@); must not point to a private or reserved address" } }, "required": [ "quote_id", "input" ], "additionalProperties": false }, "Quote": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+$" }, "price_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expires_at": { "type": "string" }, "facts": { "type": "object", "properties": { "model": { "type": "string" }, "mode": { "type": "string" }, "resolution": { "type": "string" }, "variant": { "type": "string" }, "unit": { "type": "string", "enum": [ "second", "request" ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "model", "mode", "resolution", "variant", "unit", "quantity" ] } }, "required": [ "id", "amount", "price_version", "expires_at", "facts" ] }, "Generation": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "video", "image" ] }, "model": { "type": "string" }, "mode": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "generating", "moderating", "succeeded", "failed", "canceled", "checking" ] }, "prompt": { "type": "string" }, "params": { "type": "object", "properties": { "duration": { "type": [ "number", "null" ] }, "resolution": { "type": [ "string", "null" ] }, "aspectRatio": { "type": [ "string", "null" ] } }, "required": [ "duration", "resolution", "aspectRatio" ] }, "amount": { "type": "string", "pattern": "^-?\\d+$" }, "billing": { "type": "string", "enum": [ "held", "charged", "released" ] }, "price_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "stored", "degraded", "expired", "blocked" ] }, "contentType": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "index", "url", "state", "contentType", "expiresAt" ] } }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "prompt", "input_image", "model" ] }, "input": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "created_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "model", "mode", "status", "prompt", "params", "amount", "billing", "price_version", "outputs", "error", "created_at", "finished_at" ] }, "GenerationList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Generation" } }, "next_cursor": { "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "next_cursor", "total" ] }, "Timeline": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "created", "submitted", "generating", "delivered", "failed_refunded", "canceled_refunded", "checking", "requeued" ] }, "at": { "type": "string" } }, "required": [ "code", "at" ] } } }, "required": [ "data" ] }, "V1Models": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "video", "image" ] }, "resolutions": { "type": "array", "items": { "type": "string" } }, "defaultResolution": { "type": [ "string", "null" ] }, "durations": { "anyOf": [ { "type": "object", "properties": { "min": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "default": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "min", "max", "default" ] }, { "type": "null" } ] }, "maxPromptChars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "modes": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "t2v", "i2v", "flf", "r2v", "t2i", "i2i" ] }, "needs": { "type": "object", "properties": { "image": { "type": "boolean" }, "lastImage": { "type": "boolean" }, "references": { "type": "boolean" } }, "required": [ "image", "lastImage", "references" ] }, "maxReferences": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "aspectRatios": { "type": "array", "items": { "type": "string" } }, "prices": { "type": "array", "items": { "type": "object", "properties": { "resolution": { "type": "string" }, "unit": { "type": "string", "enum": [ "second", "request" ] }, "unitPrice": { "type": "string", "pattern": "^-?\\d+$" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "seed", "generate_audio", "prompt_expansion", "negative_prompt", "watermark" ] }, "kind": { "type": "string", "enum": [ "int", "bool", "enum", "string" ] }, "min": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maxLength": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "values": { "type": "array", "items": { "type": "string" } }, "default": { "type": [ "number", "boolean", "string" ] } }, "required": [ "name", "kind" ] } } }, "required": [ "resolution", "unit", "unitPrice" ] } } }, "required": [ "mode", "needs", "maxReferences", "aspectRatios", "prices" ] } } }, "required": [ "id", "type", "resolutions", "defaultResolution", "durations", "modes" ] } } }, "required": [ "data" ] }, "V1Pricing": { "type": "object", "properties": { "price_version": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "mode": { "type": "string", "enum": [ "t2v", "i2v", "flf", "r2v", "t2i", "i2i" ] }, "resolution": { "type": "string" }, "unit": { "type": "string", "enum": [ "second", "request" ] }, "unit_price": { "type": "string", "pattern": "^-?\\d+$" }, "unit_price_usd": { "type": "string" }, "official_unit_price": { "type": "string", "pattern": "^-?\\d+$" } }, "required": [ "model", "mode", "resolution", "unit", "unit_price", "unit_price_usd" ] } } }, "required": [ "price_version", "data" ] } } } }