{ "openapi": "3.1.0", "info": { "title": "contentmaschine.ai API", "version": "1.0.0", "description": "External REST API for contentmaschine.ai.\n\n## Authentication\nAll `/v1/*` endpoints require an API key sent as a Bearer token:\n```\nAuthorization: Bearer sk-cm-\n```\nManage your API key in the Dashboard \u2192 API tab.\n\n## Scopes\nEach operation names the scope it needs in `x-required-scope`. There are five\ncontainers (`images`, `videos`, `audio`, `text`, `files`), each with `read` and `write`.\n**A write scope always includes the read scope of the same container**: a token\nwith `images:write` can also call everything that needs `images:read`. The rule does\nnot cross containers, so `images:write` does not grant `text:read`.\n\n## Async pattern\nImage generation and upscaling are asynchronous.\n1. Submit a job - receive a `job_id` (or `krea_job_id` for upscale).\n2. Poll the status endpoint until `status` is `completed` or `failed`.\n3. Download the result using the returned `download_url`.\n\n## Downloading files\nThere are TWO download paths and they do NOT authorize the same way.\n\n- `GET /v1/files/{uuid}/download` requires `files:read` **plus** the read\n scope of the container the file belongs to (an image needs `images:read`,\n a video `videos:read`, and so on). A token holding `files:read` alone gets\n a 404 for a file it may not read - deliberately a 404, not a 403, so a\n denial is indistinguishable from a nonexistent file.\n- `GET /api/files/download/{uuid}` is the older path. It is still reachable\n with the same Bearer token and it is owner-checked. For an `sk-cm-` API key\n it carries **no scope check at all** - any valid key belonging to the owner\n is served the file. An OAuth access token needs the read scope of the\n file's container, as on the v1 route, and gets a 404 without it.\n It is documented because real callers use it. Prefer the `/v1/` route.\n\nBoth return a 302 to a presigned URL valid for one hour when the file lives\nin object storage. That redirect target is a CREDENTIAL: anyone holding it\ncan read the object until it expires. Do not log it or pass it on.\n\n## Errors\nEvery error uses ONE envelope (see the `ErrorEnvelope` schema and the\n`default` response on every operation):\n```json\n{\"success\":false,\"error\":{\"message\":\"...\",\"code\":404,\"type\":\"not_found\",\n \"correlation_id\":\"0f3a...c1\"},\"timestamp\":\"2026-09-01T12:00:00+00:00\"}\n```\nBranch on `error.type`, never on `error.message` - the sentence may be\nreworded at any time. `error.code` is always the integer HTTP status.\n`error.correlation_id` is the handle to quote to support: it appears in both\nthe response and the server log line for the same request.\n\n## Breaking changes\nThree changes have already shipped on this surface. See the machine-readable\n`x-breaking-changes` block at the root of this document for the full detail.\n\n1. **Gallery item identity moved from the generation uuid to the FILE uuid.**\n `GalleryItem.uuid` is now the uuid of the file, which is what\n `/api/files/download/{uuid}` and the v1 file routes take. The generation\n uuid is still returned, under the new `generation_uuid` field.\n2. **The `category` vocabulary moved from singular to plural container names**\n (`image` -> `images`, `video` -> `videos`). Every payload now reports the\n plural, matching the scope vocabulary. The singular forms are still\n ACCEPTED on the `?category=` filter for one more release and answer with a\n `Deprecation: true` header; they will be removed.\n3. **`error.code` is now always the integer HTTP status.** The three token\n failure identifiers (`token_expired`, `token_revoked`, `token_invalid`)\n used to be put in `error.code` as strings; they are byte-identical but now\n live in the new, always-present `error.type`. If you branch on\n `error.code === \"token_revoked\"`, rename the key.", "contact": { "url": "https://contentmaschine.ai" } }, "servers": [ { "url": "https://contentmaschine.ai/api", "description": "Production" } ], "security": [ { "BearerAuth": [] }, { "OAuth2": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key (sk-cm-...) or OAuth access token" }, "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://contentmaschine.ai/api/oauth/authorize", "tokenUrl": "https://contentmaschine.ai/api/oauth/token", "refreshUrl": "https://contentmaschine.ai/api/oauth/token", "scopes": { "images:read": "Read images", "images:write": "Create and edit images (includes read)", "videos:read": "Read videos", "videos:write": "Create and edit videos (includes read)", "audio:read": "Read audio", "audio:write": "Create and edit audio (includes read)", "text:read": "Read text", "text:write": "Create and edit text (includes read)", "files:read": "Read files", "files:write": "Create and edit files (includes read)" } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "description": "The single error envelope. `error.code` is ALWAYS the integer HTTP status; `error.type` is the stable machine-readable identifier a client branches on; `error.message` is a human sentence that may be reworded without notice; `error.correlation_id` is an opaque 16-hex handle that also appears in the server log line for the same request - quote it to support. Some errors add further keys (a 403 from the scope gate adds `required_scope` and `held_scopes`, a 402 `insufficient_credits` adds `required_credits` and `available_credits` when known); the four keys above are always present.", "required": [ "success", "error", "timestamp" ], "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "required": [ "message", "code", "type", "correlation_id" ], "properties": { "message": { "type": "string", "description": "Human-readable. Do NOT branch on this." }, "code": { "type": "integer", "description": "The HTTP status, as an integer. Always.", "example": 404 }, "type": { "type": "string", "description": "Stable identifier. Branch on this. An unmapped 4xx is `client_error`, an unmapped 5xx is `server_error`.", "example": "not_found", "enum": [ "bad_request", "unauthorized", "insufficient_credits", "forbidden", "not_found", "method_not_allowed", "conflict", "payload_too_large", "unprocessable_entity", "rate_limited", "internal_error", "service_unavailable", "client_error", "server_error", "unknown_error", "insufficient_scope", "token_expired", "token_revoked", "token_invalid", "csrf_token_required", "csrf_token_invalid" ] }, "correlation_id": { "type": "string", "description": "16 lowercase hex characters.", "example": "0f3a9c2b71de44c1" }, "required_scope": { "type": "string", "nullable": true, "description": "Present on a 403 from the scope gate." }, "held_scopes": { "type": "array", "items": { "type": "string" }, "description": "Present on a 403 from the scope gate." }, "required_credits": { "type": "number", "description": "Present on a 402 insufficient_credits when the cost is known." }, "available_credits": { "type": "number", "description": "Present on a 402 insufficient_credits when the balance is known." } } }, "timestamp": { "type": "string", "format": "date-time" } } }, "Error": { "description": "Deprecated alias for ErrorEnvelope. Identical shape; use ErrorEnvelope.", "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" } ] }, "FileListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "nullable": true }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "thumbnail_url": { "type": "string", "nullable": true, "description": "Session thumbnail path, or null." }, "media": { "type": "object", "nullable": true, "description": "Video and audio only; null for images. Fields are null until the file is probed.", "properties": { "duration_ms": { "type": "integer", "nullable": true }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "fps": { "type": "object", "nullable": true, "properties": { "num": { "type": "integer" }, "den": { "type": "integer" } } }, "has_audio": { "type": "boolean", "nullable": true }, "video_codec": { "type": "string", "nullable": true }, "audio_codec": { "type": "string", "nullable": true } } } } }, "ModelList": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "tools": { "type": "array", "description": "One entry per model-driven tool. Each lists the models and aspect ratios that tool accepts.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tool identifier.", "example": "image-variator" }, "endpoint": { "type": "string", "description": "The endpoint this tool maps to.", "example": "POST /api/v1/images/vary" }, "input": { "type": "string", "description": "Summary of the required input.", "example": "file_uuid + prompt" }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Value to pass as `model`.", "example": "pro" }, "name": { "type": "string", "example": "Nano Banana Pro" }, "description": { "type": "string" }, "default": { "type": "boolean", "description": "True for the model used when `model` is omitted." }, "options": { "type": "object", "description": "Supported entries for the request `options` object, keyed by option name. Each has `param` plus `values`+`default` (enum) or `min`+`max`+`default` (range).", "additionalProperties": true }, "fields": { "type": "object", "description": "Top-level request fields whose values depend on this model, keyed by field name (for video models: `resolution` and `duration`, sent beside `prompt`, not inside `options`). Same entry shape as `options`.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Video models only. What the model accepts: start_frame, end_frame, end_frame_requires_start, reference_images (how many `reference_image_uuids`), durations (the priced steps a request snaps down to), aspect_ratios, resolutions, and audio (the clip has generated sound).", "properties": { "start_frame": { "type": "boolean" }, "end_frame": { "type": "boolean" }, "end_frame_requires_start": { "type": "boolean" }, "reference_images": { "type": "integer" }, "durations": { "type": "array", "items": { "type": "integer" } }, "aspect_ratios": { "type": "array", "items": { "type": "string" } }, "resolutions": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "boolean" } } }, "pricing": { "type": "object", "description": "Video models only. Credits per resolution, then per duration in seconds: { \"720p\": { \"8\": 12.5 } }. A combination without a price is absent.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "number" } } } } } }, "aspect_ratios": { "type": "array", "items": { "type": "string" }, "example": [ "1:1", "16:9", "9:16" ] } } } } } }, "timestamp": { "type": "string", "format": "date-time" } } }, "GalleryItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The FILE uuid. Use it with GET /v1/gallery/{uuid}, GET /v1/files/{uuid}/download and the other /v1/files routes. It was the GENERATION uuid before Phase 14 - see x-breaking-changes." }, "generation_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "The generation that produced this item. This is what `uuid` used to carry." }, "type": { "type": "string", "description": "Specific generation type, e.g. image_generation, video_generation, caption_generation." }, "category": { "type": "string", "enum": [ "images", "videos", "audio", "text", "files" ], "description": "The scope container this item belongs to. Same vocabulary as the read scopes (`images:read` reads `images`). Was singular (`image`/`video`) before Phase 14 - see x-breaking-changes." }, "container": { "type": "string", "enum": [ "images", "videos", "audio", "text", "files" ], "description": "Identical value to `category`, named in the scope vocabulary. `category` is the field existing consumers read; `container` is the explicit synonym." }, "status": { "type": "string", "enum": [ "completed", "generating", "failed" ] }, "title": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "credits_used": { "type": "number", "nullable": true }, "file": { "type": "object", "nullable": true, "description": "Present for completed file-backed items (images/videos). null otherwise.", "properties": { "uuid": { "type": "string" }, "download_url": { "type": "string", "description": "Authenticated download path; accepts the same Bearer token." }, "mime_type": { "type": "string", "nullable": true }, "size_bytes": { "type": "integer", "nullable": true }, "kind": { "type": "string", "nullable": true, "description": "image|video|document|\u2026" } } }, "text": { "type": "string", "nullable": true, "description": "Text output for text generations (captions, transcripts, etc.)." } } }, "JobQueued": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "job_id": { "type": "integer" }, "generation_id": { "type": "integer" }, "generation_uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "pending" }, "estimated_credits": { "type": "number", "format": "float" } } }, "timestamp": { "type": "string", "format": "date-time" } } }, "JobStatus": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "job_id": { "type": "integer" }, "generation_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "attempts": { "type": "integer" }, "credits_used": { "type": "number", "format": "float" }, "result": { "type": "object", "nullable": true, "properties": { "file_uuid": { "type": "string", "format": "uuid", "nullable": true }, "download_url": { "type": "string", "nullable": true }, "credits_used": { "type": "number", "format": "float" } } }, "error": { "type": "string", "nullable": true } } }, "timestamp": { "type": "string", "format": "date-time" } } }, "UpscaleQueued": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "krea_job_id": { "type": "string" }, "generation_id": { "type": "integer" }, "status": { "type": "string", "example": "processing" }, "estimated_credits": { "type": "number", "format": "float" }, "src_width": { "type": "integer" }, "src_height": { "type": "integer" } } }, "timestamp": { "type": "string", "format": "date-time" } } }, "UpscaleStatus": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processing", "completed", "failed" ] }, "file_uuid": { "type": "string", "format": "uuid", "nullable": true }, "download_url": { "type": "string", "nullable": true }, "credits_used": { "type": "number", "format": "float", "nullable": true } } }, "timestamp": { "type": "string", "format": "date-time" } } } } }, "paths": { "/v1/openapi.json": { "get": { "summary": "OpenAPI specification", "description": "Returns this OpenAPI spec. No authentication required.", "operationId": "getOpenApiSpec", "security": [], "tags": [ "Meta" ], "responses": { "200": { "description": "OpenAPI 3.1 JSON document" }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": null, "x-public": true } }, "/v1/models": { "get": { "summary": "List available models", "description": "Lists the image and video models each generation tool accepts for the `model` field,\nwith each model's supported `options`, its model-dependent top-level `fields`\n(a video model's `resolution` and `duration`) and the available `aspect_ratios`.\nNo authentication required - use this to discover valid values before calling\n`POST /v1/images/generate`, `/v1/images/vary`, `/v1/images/fuse` or `/v1/videos/generate`.", "operationId": "listModels", "security": [], "tags": [ "Meta" ], "responses": { "200": { "description": "Available models and options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": null, "x-public": true } }, "/v1/gallery": { "get": { "summary": "List your generations", "description": "Lists everything you have created - images, videos, audio and text - newest first.\nEach completed file-backed item includes a `file.download_url` you can fetch with the same Bearer token.\nText generations (captions, transcripts, etc.) include a `text` field.\n\nItems are filtered to the containers your token can read. A token holding no\nreadable container gets an empty list with a 200, never a 403: the route gate\nalready ran and this is a view filter, not an access denial.\n\nBREAKING CHANGES that landed on this response - see `x-breaking-changes`:\n`item.uuid` is now the FILE uuid (the generation uuid moved to `generation_uuid`),\nand `item.category` now reports the plural container vocabulary\n(images|videos|audio|text|files) where it used to report image|video|text|other.", "operationId": "listGallery", "tags": [ "Gallery" ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "images", "videos", "audio", "text", "files", "image", "video" ], "default": "all" }, "description": "Filter by scope container. This is the SAME vocabulary every item's `category` and `container` field reports, so a value read out of a payload can be filtered on. DEPRECATED and accepted for one more release: the singular image and video; a request using either is answered with a `Deprecation: true` response header. Anything else is a 400 whose message lists the valid values." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "completed" ] }, "description": "Only `completed` is accepted; omit for all. `generating` and `failed` are 400s, not empty pages." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A page of gallery items", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GalleryItem" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } } } }, "400": { "description": "An unknown `category`, or a `status` other than `completed`. The message lists the valid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token holds neither images:read nor videos:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": [ "images:read", "videos:read" ] } }, "/v1/gallery/browse": { "get": { "summary": "Browse one page of your images and videos with short-lived links", "description": "The paged, link-carrying form of `GET /v1/gallery`, built for viewers such as the MCP\n`show_gallery` tool. This call is free: no credits are charged, no model is called and\nno bytes are returned. Every item carries presigned URLs that expire after 15 minutes.\n\n- `thumbnail_url` opens a small stored thumbnail (or, for a video, its poster) inline.\n- `view_url` opens the original image, or plays the video, inline; `download_url` saves it.\n- **Every URL is a credential for 15 minutes**: anyone holding it can read the file. Do\n not log it or pass it on.\n- An item stored only on the server disk, or one that cannot be presigned right now, is\n still listed, with its link fields `null`, so page sizes and offsets stay stable.\n\nThe `category` is intersected with the containers your token can read: a token holding\nonly `images:read` never sees videos, whatever it asks for. A literal path, so it is never\nread as `GET /v1/gallery/{uuid}`.", "operationId": "galleryBrowse", "tags": [ "Gallery" ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "images", "videos", "all" ], "default": "all" }, "description": "Anything else, including the singular forms, is a 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 12 }, "description": "Items per page. A non-integer is a 400." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Items to skip. A negative or non-integer value is a 400." } ], "responses": { "200": { "description": "One page of items with 15-minute links.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "file_name": { "type": "string" }, "mime_type": { "type": "string", "nullable": true }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "title": { "type": "string", "nullable": true }, "thumbnail_url": { "type": "string", "nullable": true, "description": "Presigned inline URL for a small version or video poster. A credential." }, "view_url": { "type": "string", "nullable": true, "description": "Presigned inline URL for the original image or video. A credential." }, "download_url": { "type": "string", "nullable": true, "description": "Presigned download URL for the original. A credential." } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "category": { "type": "string", "enum": [ "images", "videos", "all" ] }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in_seconds": { "type": "integer" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid `category`, `limit` or `offset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token holds neither images:read nor videos:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": [ "images:read", "videos:read" ] } }, "/v1/gallery/{uuid}": { "get": { "summary": "Get one generation", "description": "Returns a single item you own, including its full `input_data`/`output_data` and a download-ready `file` when available. NOTE the path parameter is the FILE uuid, which is what the list response returns as `uuid` - the generation uuid is a different value and is returned as `generation_uuid`. See `x-breaking-changes`.", "operationId": "getGalleryItem", "tags": [ "Gallery" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The FILE uuid, which is what the gallery list returns as `uuid`; not the generation uuid." } ], "responses": { "200": { "description": "The generation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/GalleryItem" }, { "type": "object", "properties": { "input_data": { "type": "object", "description": "The original request payload." }, "output_data": { "type": "object", "description": "The result payload, with internal error/diagnostic fields redacted." }, "error": { "type": "boolean", "description": "Present and true when the generation failed (status=failed). Internal error detail is not exposed." } } } ] } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not owned by you", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": [ "images:read", "videos:read" ] } }, "/v1/files/upload": { "post": { "summary": "Upload a source file", "description": "Upload a file into your library and receive a `file_uuid`. This is the single\ningest route for the whole API: pass the uuid to the image endpoints\n(`/v1/images/vary`, `/fuse`, `/upscale`, `/remove-background`, `/describe`,\n`/instagram-enhance`), as a video start frame, to `/v1/audio/transcribe`, or to\n`/v1/videos/merge`.\n\nACCEPTED TYPES (this list is read from the server's own allowlist, not restated):\n`image/png`, `image/jpeg`, `image/webp`, `image/gif`, `audio/mpeg`, `audio/wav`, `video/mp4`.\nThe type is SNIFFED from the bytes; the filename extension is not trusted.\n\nSIZE LIMITS, and they are MEASURED against the deployed server rather than copied\nfrom a constant:\n- images: 25 MB\n- audio and video: 48 MB\n\nThe 48 MB figure is deliberately below the gateway request-body limit of 50 MB,\nwhich was measured byte-for-byte on the deployed stack: a 52,428,800-byte request\nbody was accepted and 52,428,801 bytes was cut off mid-upload with an HTML error\npage. The margin exists so that an oversized upload gets THIS API's JSON 413 with a\nusable message instead of the gateway's HTML. Note the gateway limit applies to the\nwhole multipart REQUEST BODY - the file plus framing plus the filename - not to the\nfile alone. A body past that limit does not produce a JSON error at all.\n\n`width` and `height` are returned for images and are null for audio and video.\nThe response shape is otherwise unchanged from when this route was images-only.", "operationId": "uploadFile", "tags": [ "Files" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload. Type is sniffed from the bytes." } } } } } }, "responses": { "201": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "file_uuid": { "type": "string", "description": "Pass this as file_uuid to the image endpoints." }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "width": { "type": "integer", "nullable": true, "description": "Images only; null for audio and video." }, "height": { "type": "integer", "nullable": true, "description": "Images only; null for audio and video." } } } } } } } }, "400": { "description": "No file field, or a file the server could not read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Too large: over 25 MB for an image, or over 48 MB for audio/video. A request BODY over the 50 MB gateway limit is cut off before this handler runs and returns an HTML page instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Unsupported type. The message lists the accepted mime types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:write" } }, "/v1/images/generate": { "post": { "summary": "Generate an image (async)", "description": "Queue a text-to-image generation job.\nReturns immediately with a `job_id`.\nPoll `GET /v1/jobs/{id}` until `status` is `completed`, then use `download_url`.", "operationId": "generateImage", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Text description of the image to generate.", "example": "A serene mountain lake at golden hour, photorealistic" }, "model": { "type": "string", "description": "Model to use for generation. Discover the full list with options via GET /v1/models.", "enum": [ "standard", "lite", "pro", "flux", "seedream", "seedream5", "gpt-image-2.5-flare" ], "default": "standard" }, "aspect_ratio": { "type": "string", "description": "Aspect ratio of the generated image.", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "default": "1:1" }, "options": { "type": "object", "description": "Model-specific options.", "properties": { "seed": { "type": "integer", "description": "Seed for reproducible results." }, "temperature": { "type": "number", "format": "float", "description": "Creativity (0.0\u20132.0). Lower = closer to prompt. Ignored by the Gemini models, which no longer accept it.", "default": 1 }, "resolution": { "type": "string", "enum": [ "1024", "2048", "4096" ], "description": "Output resolution (pro model only).", "default": "2048" } } } } }, "examples": { "standard": { "summary": "Standard model", "value": { "prompt": "A futuristic city skyline at night", "model": "standard", "aspect_ratio": "16:9" } }, "flux": { "summary": "Flux with seed", "value": { "prompt": "Portrait of a red fox in autumn forest", "model": "flux", "aspect_ratio": "1:1", "options": { "seed": 42, "temperature": 0.7 } } } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueued" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/vary": { "post": { "summary": "Create an image variation (async, image-to-image)", "description": "Generate a new image based on a source image, guided by a prompt.\nGive the source either as a library `file_uuid` (upload via POST /v1/files/upload)\nor inline as base64 in `image_data`; exactly one of the two.\nReturns immediately with a `job_id` - poll `GET /v1/jobs/{id}` until\n`status` is `completed`, then use `download_url`.\nDiscover valid `model` values via GET /v1/models.\n\nWith `guided: true` the prompt is wrapped in the instructions the Image Variator\nuses (shaped by `variability`), `prompt` may be empty, and the editing fields apply:\n`mask_data` (inpainting: a PNG the size of the source, black marks what to regenerate),\n`crop` (vary only that region), `extension_direction` and `aspect_ratio_processed`\n(the source was padded with lime green #00FF00 areas to fill). Without `guided`,\n`prompt` is required and sent to the model as written.", "operationId": "varyImage", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_uuid": { "type": "string", "description": "UUID of a source image already in your library. Use this or `image_data`.", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "image_data": { "type": "string", "description": "The source image inline, as base64 or a data URL (PNG, JPEG, WebP or GIF). Use this or `file_uuid`." }, "prompt": { "type": "string", "description": "How the variation should differ from the source. Required unless `guided` is true.", "example": "Same composition, but at sunset with warm golden light" }, "model": { "type": "string", "description": "Model to use for the variation.", "enum": [ "standard", "lite", "pro", "flux", "seedream", "seedream5" ], "default": "standard" }, "aspect_ratio": { "type": "string", "description": "Output aspect ratio. Omit to keep the source ratio.", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ] }, "variability": { "type": "integer", "description": "How far the result may stray from the source (1 = subtle, 5 = experimental).", "minimum": 1, "maximum": 5, "default": 1 }, "options": { "type": "object", "description": "Model-specific options.", "properties": { "resolution": { "type": "string", "enum": [ "1024", "2048", "4096" ], "description": "Output resolution (pro model only).", "default": "2048" }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Seed for reproducible output, where the model supports one." } } }, "guided": { "type": "boolean", "default": false, "description": "Wrap the prompt in the Image Variator instructions and allow the editing fields below." }, "mask_data": { "type": "string", "description": "Guided only. Inpainting mask as base64 PNG, same size as the source: black pixels are regenerated, the rest is kept." }, "crop": { "type": "object", "description": "Guided only. Vary just this region of the source, in source pixels.", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 } } }, "extension_direction": { "type": "string", "enum": [ "top", "right", "bottom", "left" ], "description": "Guided only. The side the source was extended on; the lime green area is filled." }, "aspect_ratio_processed": { "type": "boolean", "default": false, "description": "Guided only. The source was padded to a new aspect ratio with lime green areas to fill." } } }, "examples": { "subtle": { "summary": "Subtle restyle", "value": { "file_uuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "prompt": "Same scene at sunset, warm light", "model": "standard", "variability": 2 } }, "experimental": { "summary": "Bold variation with Flux", "value": { "file_uuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "prompt": "Reimagine as a watercolor painting", "model": "flux", "aspect_ratio": "1:1", "variability": 5 } } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueued" } } } }, "400": { "description": "No source image or both forms of it, a missing prompt, an unusable image, or invalid editing fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "File belongs to another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Source file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/fuse": { "post": { "summary": "Fuse multiple images (async, image-to-image)", "description": "Combine 2\u201310 images into a single cohesive image, guided by an optional prompt.\nGive the sources as library `file_uuids` or inline as base64 in `images`; exactly one of the two.\nReturns immediately with a `job_id` - poll `GET /v1/jobs/{id}` until `status` is `completed`.\nDiscover valid `model` values via GET /v1/models (same set as variation).", "operationId": "fuseImages", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_uuids": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 10, "description": "UUIDs of 2\u201310 source images already in your library. Use this or `images`." }, "images": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 10, "description": "2\u201310 source images inline, each base64 or a data URL (PNG, JPEG, WebP or GIF). Use this or `file_uuids`." }, "prompt": { "type": "string", "description": "Optional direction for how the images should be combined.", "example": "Place the character from the first image into the landscape of the second" }, "model": { "type": "string", "description": "Model to use for the fusion.", "enum": [ "standard", "lite", "pro", "flux", "seedream", "seedream5" ], "default": "standard" }, "aspect_ratio": { "type": "string", "description": "Aspect ratio of the result.", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "default": "1:1" }, "options": { "type": "object", "description": "Model-specific options.", "properties": { "resolution": { "type": "string", "enum": [ "1024", "2048", "4096" ], "description": "Output resolution (pro model only).", "default": "2048" }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Seed for reproducible output, where the model supports one." } } } } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueued" } } } }, "400": { "description": "Fewer than 2 or more than 10 sources, both forms, or an unusable image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A file belongs to another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "A source file was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/describe": { "post": { "summary": "Describe / caption an image (sync)", "description": "Generate a natural-language description or caption (e.g. alt text) for an image in your library.\nSynchronous - the description is returned directly in the response.", "operationId": "describeImage", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_uuid" ], "properties": { "file_uuid": { "type": "string", "description": "UUID of an image already in your library." }, "prompt": { "type": "string", "description": "Optional instruction to steer the description.", "example": "Write concise SEO alt text" } } } } } }, "responses": { "200": { "description": "Description generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "text": { "type": "string", "description": "The generated caption/description." }, "generation_id": { "type": "integer" }, "credits_used": { "type": "number" }, "processing_time_ms": { "type": "integer" } } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "File belongs to another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Source file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:read" } }, "/v1/videos/generate": { "post": { "summary": "Generate a video (async)", "description": "Queue a text-to-video generation job (optionally seeded by a library image as the start frame).\nReturns immediately with a `job_id` - poll `GET /v1/jobs/{id}` until `status` is `completed`.\nAllowed `duration` and `resolution` values depend on the chosen model.", "operationId": "generateVideo", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Description of the video to generate.", "example": "A timelapse of clouds rolling over a mountain range at dawn" }, "model": { "type": "string", "description": "Video model to use. omni is Gemini Omni Flash. The retired id veo3 is still accepted and runs on omni.", "enum": [ "omni", "grok", "kling", "seedance" ], "default": "omni" }, "aspect_ratio": { "type": "string", "description": "Aspect ratio of the video. Defaults to the start image's shape when image_file_uuid is given, else 16:9. omni renders 16:9 or 9:16 only: portrait ratios become 9:16, square and landscape ratios 16:9.", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ] }, "duration": { "type": "integer", "description": "Length in seconds. omni: 3 to 10 (values outside are clamped). grok: 5, 8, 10 or 15. kling: 3, 5, 8, 10 or 15. seedance: 4, 6, 8, 10, 15, 20 or 30. For grok, kling and seedance other values snap down to the nearest of these (below the first, the first), so the generated length is the billed length; the 202 response reports the duration used.", "default": 8 }, "resolution": { "type": "string", "enum": [ "720p", "480p", "standard", "pro" ], "description": "Per model: omni 720p; grok 480p or 720p; kling standard or pro; seedance 480p or 720p. Omit it for the model's default (omni 720p, grok 480p, kling standard, seedance 480p); a value the model does not support also falls back to that default." }, "negative_prompt": { "type": "string", "description": "What the video should avoid. omni has no negative prompt parameter, so it is appended to the prompt text." }, "image_file_uuid": { "type": "string", "description": "Optional uuid of an image already in your library to use as the start frame (no upload needed)." }, "start_frame_data": { "type": "string", "description": "The start frame inline, as base64 or a data URL. Use this or `image_file_uuid`." }, "end_image_file_uuid": { "type": "string", "description": "Optional uuid of a library image to use as the end frame. Needs a start frame; omni, kling and seedance only." }, "end_frame_data": { "type": "string", "description": "The end frame inline, as base64 or a data URL. Use this or `end_image_file_uuid`." }, "reference_image_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 3, "description": "omni only: up to 3 images from your library the video should match (look, characters, products)." }, "client_ref": { "type": "string", "maxLength": 128, "description": "Idempotency key (letters, digits, . _ : -). A repeat with the same client_ref within 24 hours returns the first response and is not charged again; while the first is still being queued the repeat gets 409 request_in_progress." }, "options": { "type": "object", "description": "Model-specific options." } } }, "examples": { "text_to_video": { "summary": "Text to video", "value": { "prompt": "A neon city street in the rain, cinematic", "model": "omni", "aspect_ratio": "16:9", "duration": 8 } } } } } }, "responses": { "202": { "description": "Job queued. `data` also carries `model`, `duration`, `resolution` and `aspect_ratio`: the values that will be generated and billed, after defaults and snapping. A `client_ref` repeat gets the first response again, with the header `Idempotent-Replayed: true`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueued" } } } }, "400": { "description": "Missing prompt, both forms of one frame, or a frame that is not a usable image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "image_file_uuid or end_image_file_uuid not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A frame file belongs to another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "A frame image is larger than 10 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "request_in_progress: the first request with this client_ref is still being queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "videos:write" } }, "/v1/jobs/{id}": { "get": { "summary": "Poll job status", "description": "Returns the current status of an async job. When `status` is `completed`, `result.download_url` contains the image URL.", "operationId": "getJobStatus", "tags": [ "Jobs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The job_id returned by the call that started the job." } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatus" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": [ "images:read", "videos:read", "audio:read", "text:read", "files:read" ] } }, "/v1/images/upscale": { "post": { "summary": "Upscale an image (async)", "description": "Submit an upscale job for an image already in your library.\nReturns a `krea_job_id` and `generation_id`.\nPoll `GET /v1/images/upscale-status` with those values.\n\nTypical flow:\n1. Generate an image \u2192 get `result.file_uuid`\n2. Upscale that `file_uuid` \u2192 get `krea_job_id` + `generation_id`\n3. Poll upscale-status until `completed`", "operationId": "upscaleImage", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_uuid" ], "properties": { "file_uuid": { "type": "string", "format": "uuid", "description": "UUID of a file in your library (e.g. from a completed generate job)." }, "provider": { "type": "string", "enum": [ "krea_topaz", "krea_bloom" ], "default": "krea_topaz", "description": "krea_topaz = generative quality; krea_bloom = creative detail." }, "scale": { "type": "integer", "enum": [ 2, 4, 6, 8 ], "default": 2, "description": "Upscale multiplier." }, "auto_downscale": { "type": "boolean", "default": false, "description": "When the output would exceed the provider limit (krea_topaz 16000px, krea_bloom 10000px on the longest side), shrink the source to fit first. Without it such a request answers 400 `needs_downscale` with the suggested `target_width`/`target_height`, and nothing is charged." } } }, "example": { "file_uuid": "550e8400-e29b-41d4-a716-446655440000", "provider": "krea_topaz", "scale": 2 } } } }, "responses": { "202": { "description": "Upscale job submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpscaleQueued" } } } }, "400": { "description": "Validation error or image too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/region-edit": { "post": { "summary": "Edit a masked region of an image (async)", "description": "Regenerate the masked area of an image already in your library from a prompt,\nusing GPT Image 2.5 Sunburst. Everything outside the masked area is preserved.\nReturns a `job_id`; poll `GET /v1/jobs/{id}` until `completed`. There is no\nregion-edit status route.\n\nSupply exactly one mask, never both: `mask_file_uuid` (a PNG already in your\nlibrary) or `mask` (inline base64 PNG bytes). Neither is a 400, and both is a 400.\nThe mask must match the source image's pixel dimensions exactly and must have an\nalpha channel: fully transparent pixels (alpha 0) mark the area to change, opaque\npixels (alpha 255) mark the area to keep. The mask file must be smaller than\n4194304 bytes (4 MB); an inline `mask` whose base64 payload is longer than 5592408 characters is refused before it is decoded.\nThe inline form exists because `files/upload` is not exposed as an MCP tool, so\ninline is the only way an agent can supply a freshly drawn mask.\n\nEvery mask check runs before any credit is reserved: a refused mask costs nothing.\nA request that passes is charged the current `image_region_edit` price, reported\nas `estimated_credits` in the 202.", "operationId": "regionEditImage", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_file_uuid", "prompt" ], "properties": { "source_file_uuid": { "type": "string", "format": "uuid", "description": "UUID of the image in your library to edit." }, "prompt": { "type": "string", "description": "What to put inside the masked area." }, "mask_file_uuid": { "type": "string", "format": "uuid", "description": "UUID of a mask PNG already in your library. Send this OR `mask`, never both. Same pixel dimensions as the source, with an alpha channel: transparent = change, opaque = keep." }, "mask": { "type": "string", "description": "The mask PNG inline, as unwrapped base64 (an optional \"data:image/png;base64,\" prefix is accepted). Send this OR `mask_file_uuid`, never both. Smaller than 4194304 bytes decoded; a payload longer than 5592408 base64 characters (prefix excluded) is refused before decoding. Same pixel dimensions as the source, with an alpha channel: transparent = change, opaque = keep." } } }, "example": { "source_file_uuid": "550e8400-e29b-41d4-a716-446655440000", "mask_file_uuid": "6ba7b810-9dad-41d1-80b4-00c04fd430c8", "prompt": "Replace the sky with a warm sunset" } } } }, "responses": { "202": { "description": "Region edit job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueued" } } } }, "400": { "description": "Validation error: a missing or malformed field, neither or both mask forms, or a mask that is not an alpha PNG, is too large, or does not match the source image's dimensions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The source image or the mask file is not yours, or the API key lacks images:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Source image or mask file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The job could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/remove-background": { "post": { "summary": "Remove image background (async)", "description": "Queue a background removal for an image: a library `file_uuid` or the image inline\nas base64 in `image_data`; exactly one of the two. JPEG, PNG or WebP.\nUses AI triangulation matting (two Gemini passes + per-pixel alpha computation).\nReturns immediately with a `job_id` - poll `GET /v1/jobs/{id}` until `status` is\n`completed`; the result carries `file_uuid` and `download_url` of the PNG.\nThis route answered synchronously before 2026-10-09 - see `x-breaking-changes`.\n\nCost: 0.20 credits per call, reserved when the job is queued.", "operationId": "removeBackground", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_uuid": { "type": "string", "format": "uuid", "description": "UUID of an image file in your library (JPEG, PNG, or WebP). Use this or `image_data`." }, "image_data": { "type": "string", "description": "The image inline, as base64 or a data URL (JPEG, PNG, or WebP). Use this or `file_uuid`." }, "subject_hint": { "type": "string", "maxLength": 80, "description": "Optional hint to identify the subject, e.g. \"the person\" or \"the car\"." } } }, "example": { "file_uuid": "550e8400-e29b-41d4-a716-446655440000", "subject_hint": "the person" } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueued" } } } }, "400": { "description": "No image or both forms of it, an unsupported image type, or a subject_hint over the limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized access to file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/upscale-status": { "get": { "summary": "Poll upscale status", "description": "Returns the current status of an upscale job. When `status` is `completed`, `download_url` contains the high-resolution image.", "operationId": "getUpscaleStatus", "tags": [ "Images" ], "parameters": [ { "name": "krea_job_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "krea_job_id from the upscale response." }, { "name": "generation_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "generation_id from the upscale response." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "default": "krea_topaz" } }, { "name": "scale", "in": "query", "required": false, "schema": { "type": "integer", "default": 2 } } ], "responses": { "200": { "description": "Upscale status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpscaleStatus" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Generation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:read" } }, "/v1/images/style-transfer": { "post": { "summary": "Apply the style of one image to another", "description": "Re-renders the content image in the visual style of the style image.\n\nGive each image either as a library file uuid (`file_uuid` for the content image,\n`style_file_uuid` for the style reference) or INLINE as a base64 data URL\n(`contentImage`, `styleImage`). One of each pair is required; sending both of a pair\nis a 400. Returns when the image is ready; there is no job to poll.", "operationId": "styleTransferImage", "tags": [ "Images" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_uuid": { "type": "string", "description": "Uuid of a library image to restyle (the content image). Use this or `contentImage`.", "format": "uuid" }, "style_file_uuid": { "type": "string", "description": "Uuid of a library image whose style is applied. Use this or `styleImage`.", "format": "uuid" }, "contentImage": { "type": "string", "description": "Base64 data URL of the image to restyle. Use this or `file_uuid`." }, "styleImage": { "type": "string", "description": "Base64 data URL of the style reference. Use this or `style_file_uuid`." }, "styleStrength": { "type": "number", "format": "float", "default": 0.7, "description": "How strongly the style is applied." }, "modelVariant": { "type": "string", "description": "Model variant. Defaults to `standard`." }, "modelOptions": { "type": "object", "additionalProperties": true, "description": "Per-model options; see GET /v1/models." } } } } } }, "responses": { "200": { "description": "The restyled image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "A missing content or style image, both forms of one image, or an unusable image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "A file uuid belongs to another user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "A file uuid was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/expand": { "post": { "summary": "Expand an image to a new aspect ratio (outpainting)", "description": "Generates the missing area around an image so it fills a different aspect ratio.\n\nGive the image either as a library file uuid (`file_uuid`) or INLINE as a base64\ndata URL (`imageData`), not both. `targetAspectRatio` must be one of the ratios\nGET /v1/models reports for this tool.", "operationId": "expandImage", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_uuid": { "type": "string", "description": "Uuid of a library image to expand. Use this or `imageData`.", "format": "uuid" }, "imageData": { "type": "string", "description": "Base64 data URL of the image to expand. Use this or `file_uuid`." }, "targetAspectRatio": { "type": "string", "description": "Target ratio, e.g. \"16:9\"." }, "contextPrompt": { "type": "string", "description": "Optional hint describing what should fill the new area." }, "modelVariant": { "type": "string", "description": "Model variant. Defaults to `standard`." }, "modelOptions": { "type": "object", "additionalProperties": true, "description": "Per-model options; see GET /v1/models." } }, "required": [ "targetAspectRatio" ] } } } }, "responses": { "200": { "description": "The expanded image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Missing image, both file_uuid and imageData, or an aspect ratio this tool does not accept (the message lists the valid ones).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "file_uuid belongs to another user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "file_uuid was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/mockup": { "post": { "summary": "Start a product-mockup generation (async)", "description": "Places one or more product images into a generated scene.\n\nASYNCHRONOUS, and NOT through the normal job endpoint: it returns a `job_id`\nthat is polled with `GET /v1/images/mockup-status`, not with `GET /v1/jobs/{id}`.\nGive the product image as a library file uuid (`file_uuid`), or INLINE as base64\n(`images`, or the single-image `imageData` + `mimeType` pair).", "operationId": "startMockupGeneration", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "What the mockup scene should show." }, "file_uuid": { "type": "string", "description": "Uuid of a library image to place in the scene. Use this or the inline `images` / `imageData`.", "format": "uuid" }, "images": { "type": "array", "description": "Product images. Each entry is {data, mimeType}. Alternatively send the single-image `imageData` + `mimeType` pair.", "items": { "type": "object", "properties": { "data": { "type": "string" }, "mimeType": { "type": "string" } } } }, "imageData": { "type": "string", "description": "Single-image alternative to `images`: a base64 payload. Requires `mimeType`." }, "mimeType": { "type": "string", "description": "Mime type of `imageData`." }, "variability": { "type": "integer", "description": "How many variations to produce. Defaults to 1." }, "modelVariant": { "type": "string", "description": "Model variant. Defaults to `standard`." }, "modelOptions": { "type": "object", "additionalProperties": true, "description": "Per-model options; see GET /v1/models." } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "Queued. Poll GET /v1/images/mockup-status with the returned job_id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "No image (`file_uuid`, `images` or `imageData`/`mimeType`), or file_uuid together with inline data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "file_uuid belongs to another user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "file_uuid was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/images/mockup-status": { "get": { "summary": "Poll a mockup generation", "description": "Returns the status of a mockup job started by POST /v1/images/mockup. Note this is a SEPARATE poller from GET /v1/jobs/{id} - a mockup job id is not a jobs-endpoint id.", "operationId": "getMockupStatus", "tags": [ "Images" ], "parameters": [ { "name": "job_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The job_id returned by POST /v1/images/mockup." } ], "responses": { "200": { "description": "Mockup job status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "job_id parameter is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such job, or it does not belong to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:read" } }, "/v1/images/instagram-enhance": { "post": { "summary": "Generate a social caption from images you own", "description": "Produces a platform-shaped caption - and on headline platforms a headline and a\ndescription - from 1 to 10 images.\n\n**SCOPES: this route needs `images:write` to CALL, but its OUTPUT reads as `text`**\n(D-15-23). The result is stored as a `caption_generation`, which classifies into the\n`text` container, so finding it later through /v1/gallery, /v1/library or\n/v1/jobs/{id} needs `text:read`. A token holding only `images:write` can run this\nand be charged for it, and then not be able to read the result back. The response\nbody returns the caption directly, so a single call still works.\n\nGive the images as library `file_uuids` (upload with POST /v1/files/upload) or inline\nas base64 in `images`; exactly one of the two.\nLimits: 10485760 bytes per image, 26214400 bytes across the call,\n`context` at most 2000 characters.\n\nThe prompt is built SERVER-SIDE. There is deliberately no raw `prompt` field: it\nwould turn the caption credit path into a general-purpose vision prompt. `context`\nand the blueprint fields are untrusted text spliced into a model instruction and the\nbuilder emits a guard sentence about them - a mitigation, not a guarantee.", "operationId": "instagramEnhance", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_uuids": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uuid" }, "description": "Uuids of images you own. Must be a real JSON array. Use this or `images`." }, "images": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string" }, "description": "The images inline, each base64 or a data URL (PNG, JPEG, WebP or GIF). Must be a real JSON array. Use this or `file_uuids`." }, "platform": { "type": "string", "description": "Target platform, e.g. \"Instagram\" or \"TikTok\"." }, "length": { "type": "string", "enum": [ "Short", "Medium", "Long", "Very Long" ], "description": "Caption length." }, "tone": { "type": "string", "description": "Tone, e.g. \"Friendly\"." }, "language": { "type": "string", "description": "Output language, e.g. \"English\"." }, "context": { "type": "string", "description": "Extra brief for the model. At most 2000 characters." }, "blueprint": { "type": "object", "description": "Optional StoryBrand fields: title, businessName, hero, problem, guide, plan, callToAction, avoidFailure, success.", "additionalProperties": true }, "additional_hashtags": { "description": "Your own hashtags as a string, or their count as an integer. On TikTok the model is asked for the remainder of five.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] } }, "required": [ "platform", "length", "tone", "language" ] } } } }, "responses": { "200": { "description": "The generated caption.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "headline": { "type": "string", "nullable": true, "description": "Headline platforms only." }, "description": { "type": "string", "nullable": true }, "caption": { "type": "string" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "credits_used": { "type": "number", "format": "float", "description": "Credits actually charged." }, "generation_id": { "type": "integer", "description": "The stored generation, readable with text:read." }, "processing_time_ms": { "type": "integer", "description": "Wall clock inside the handler." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad input: a missing field, an over-long value, more than 10 images, both image forms, an unusable inline image, or a JSON object where an array was required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "A file_uuid is unknown or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The images exceed the per-image or total byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "One of the files is not an image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The captioning provider is unavailable or rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/videos/quote": { "get": { "summary": "Price of one video generation", "description": "The credits `POST /v1/videos/generate` would reserve for this model, duration and resolution, after the same defaults and snapping. Nothing is charged.", "operationId": "quoteVideo", "tags": [ "Videos" ], "parameters": [ { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "omni", "grok", "kling", "seedance" ], "default": "omni" }, "description": "Video model." }, { "name": "duration", "in": "query", "required": false, "schema": { "type": "integer", "default": 8 }, "description": "Seconds; snapped down to a priced step like videos/generate." }, { "name": "resolution", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "720p", "480p", "standard", "pro" ] }, "description": "Omit for the model default." }, { "name": "aspect_ratio", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ] } } ], "responses": { "200": { "description": "The price.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "model": { "type": "string" }, "duration": { "type": "integer" }, "resolution": { "type": "string" }, "aspect_ratio": { "type": "string" }, "credits": { "type": "number" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "duration is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold videos:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "videos:read" } }, "/v1/videos/merge": { "post": { "summary": "Concatenate two videos you own", "description": "Joins exactly two videos already in your library, in the order given, into one new\nvideo. Input is FILE REFERENCES, never a multi-file upload. There is no N-way merge.\n\n**SYNCHRONOUS. There is no job to poll, and there is a hard latency ceiling.**\nThe merge runs inside this request via ffmpeg. Which path runs decides everything:\ntwo clips that already share codec, resolution, frame rate and pixel format are\nstream-copied (`merge_method: lossless`); anything else is fully re-encoded\n(`reencode`), roughly an order of magnitude slower. Clips from two different\ngeneration models routinely differ, so the slow path is not an edge case.\n\nMEASURED on the deployed stack (2026-08-31):\n```\nlossless 2 x 30 s in -> 60 s out : 4.2 s 200\nlossless 2 x 180 s in -> 360 s out : 7.0 s 200\nreencode 2 x 30 s in -> 60 s out : 32.7 s 200\nreencode 2 x 180 s in : 120.2 s 504\n```\nThe ceiling is the gateway read timeout of 120 seconds, not a limit this API can\nraise from PHP. The re-encode path costs about 0.55 s per second of OUTPUT, so treat\n**about 3 minutes of COMBINED input as the practical limit for mismatched clips**.\nPast it you receive a bare gateway 504 with NO JSON body - the only response on this\nAPI that is not the standard envelope - the work is discarded, and no output file is\nregistered. The stream-copy path is unconstrained at any length this API can ingest,\nbecause the 48 MB per-file upload cap binds first.\n\n`credits_used` is always 0 today. Merging is not currently billed; the field is\nreturned explicitly rather than left to be inferred.", "operationId": "mergeVideos", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_uuids": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "format": "uuid" }, "description": "Exactly two uuids of videos you own, in join order." } }, "required": [ "file_uuids" ] } } } }, "responses": { "200": { "description": "The merged video.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "file_uuid": { "type": "string", "format": "uuid" }, "download_url": { "type": "string", "description": "Authenticated download path for the merged file." }, "merge_method": { "type": "string", "enum": [ "lossless", "reencode" ], "description": "Which ffmpeg path ran." }, "credits_used": { "type": "number", "format": "float", "description": "Always 0 today." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Not exactly two file_uuids, or a malformed body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "A file_uuid is unknown or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "One of the files is not a video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Gateway timeout at 120 s. NOT a JSON envelope - this response comes from the gateway, not from the application. The merge was discarded and no file was created. Retry with shorter inputs, or with clips that share codec/resolution/frame rate so the stream-copy path runs." }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "videos:write" } }, "/v1/files/{uuid}": { "delete": { "summary": "Delete a file you own", "description": "Soft-deletes the file. The stored object is reclaimed by a background cleanup job, not synchronously here. A uuid belonging to another account answers 404, identical to an unknown one.", "operationId": "deleteFile", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of an item in your library (from the gallery or library list, or a finished job)." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:write" } }, "/v1/files/{uuid}/download": { "get": { "summary": "Download a file you own", "description": "Returns the bytes, NOT a JSON envelope. Files in object storage answer 302 with a\npresigned URL valid for one hour; locally stored files are streamed directly.\n\n**The redirect target is a credential.** Anyone holding that presigned URL can read\nthe object until it expires. Do not log it, cache it in a shared cache, or pass it on.\n\n**Authorization here is two-layer, and `files:read` is only the outer one.** The\nroute gate checks `files:read`; the handler then checks that your token can read the\nfile's own container. A token holding `files:read` but not `images:read` gets 404 for\nan image - a 404 rather than a 403, so a denial cannot be told apart from a\nnonexistent file.\n\nContrast `GET /api/files/download/{uuid}`, which is also documented here: it is\nowner-checked but has NO scope check at all.", "operationId": "downloadFileV1", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of an item in your library (from the gallery or library list, or a finished job)." } ], "responses": { "200": { "description": "The file bytes (locally stored files).", "content": { "application/octet-stream": [] } }, "302": { "description": "Redirect to a presigned URL valid for one hour. The Location header is a credential." }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, not yours, OR readable only by a container scope your token lacks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:read" } }, "/v1/files/{uuid}/download-link": { "get": { "summary": "Get a short-lived download link and a preview for a file you own", "description": "The JSON form of `GET /v1/files/{uuid}/download`, built for agent callers that cannot\nfollow an authenticated URL or show a binary body. No credits are charged and the file\nstays private: its visibility is not changed.\n\n- `download_url` is a presigned, unauthenticated URL for the ORIGINAL file, valid for 15\n minutes (`expires_at`). **It is a credential for that time**: anyone holding it can\n read the file. Do not log it or pass it on. It is `null` for a file stored only on the\n server disk (no expiring link can be issued); `link_unavailable_reason` then says why.\n- `preview` is set for raster images only: a reduced JPEG (at most 1024 px on the long\n edge and about 350 KB), base64-encoded. It is never the original bytes. `null` for\n other files, SVG, or an image that cannot be decoded.\n\nAuthorization is the same two-layer check as the download route: `files:read` at the\ngate, then the read scope of the file's own container. A denial is a 404, never a 403.", "operationId": "getFileDownloadLinkV1", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of an item in your library (from the gallery or library list, or a finished job)." } ], "responses": { "200": { "description": "File metadata, a 15-minute download link and, for images, a preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "download_url": { "type": "string", "nullable": true, "description": "Presigned URL for the original file, valid 15 minutes. A credential." }, "view_url": { "type": "string", "nullable": true, "description": "Presigned URL that opens the original in the browser instead of downloading it, valid 15 minutes. Raster images only. A credential." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_in_seconds": { "type": "integer", "nullable": true }, "link_unavailable_reason": { "type": "string", "nullable": true }, "preview": { "type": "object", "nullable": true, "properties": { "mime_type": { "type": "string", "enum": [ "image/jpeg" ] }, "base64": { "type": "string", "description": "Reduced JPEG, base64. Never the original bytes." }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, not yours, OR readable only by a container scope your token lacks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:read" } }, "/v1/files/view-links": { "get": { "summary": "Get short-lived view links for up to 20 of your images", "description": "The batch, view-only form of `GET /v1/files/{uuid}/download-link`, built for image\nviewers such as the MCP `show_images` tool. No credits are charged, no image is decoded\nand no bytes are returned: every entry carries presigned URLs valid for 15 minutes.\n\n- `thumbnail_url` opens a small stored thumbnail inline when one exists, otherwise the\n same image as `view_url`.\n- `view_url` opens the original inline in the browser; `download_url` saves it.\n- **Every URL is a credential for 15 minutes**: anyone holding it can read the file. Do\n not log it or pass it on.\n\nOnly raster images (JPEG, PNG, WebP, GIF, AVIF) stored in object storage get links. Any\nuuid that is unknown, not yours, readable only by a container scope your token lacks,\nnot a raster image (SVG, PDF and others never get inline links), stored only on the\nserver disk, or not presignable right now is listed in `not_found` instead. One list for\nall of these, so it reveals nothing about files you cannot read.\n\nAuthorization per uuid is the same two-layer check as the download route: `files:read`\nat the gate, then the read scope of the file's own container.", "operationId": "getFileViewLinksV1", "tags": [ "Files" ], "parameters": [ { "name": "uuids", "in": "query", "required": true, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20 }, "description": "1 to 20 file uuids, comma-separated in the query string. Duplicates are ignored." } ], "responses": { "200": { "description": "View links for the images that can be shown, and the uuids that cannot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "thumbnail_url": { "type": "string", "description": "Presigned inline URL for a small version. A credential." }, "view_url": { "type": "string", "description": "Presigned inline URL for the original. A credential." }, "download_url": { "type": "string", "description": "Presigned download URL for the original. A credential." }, "expires_at": { "type": "string", "format": "date-time" } } } }, "not_found": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in_seconds": { "type": "integer" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "`uuids` is missing, holds something that is not a uuid, or names more than 20 files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:read" } }, "/v1/files/{uuid}/video-link": { "get": { "summary": "Get short-lived playback and download links for one of your videos", "description": "Built for video players such as the MCP `show_video` tool. This call is free: no credits\nare charged, no model is called and no bytes are returned. The links expire after 15\nminutes.\n\n- `video_url` plays the video inline with its real content type; `download_url` saves it.\n- `poster_url` is the stored thumbnail when there is one, otherwise `null`.\n- **Every URL is a credential for 15 minutes**: anyone holding it can read the file. Do\n not log it or pass it on.\n- A video stored only on the server disk, or one that cannot be presigned right now,\n answers 200 with `available: false`, every URL `null` and `reason` saying why.\n\nOnly MP4, WebM and QuickTime videos are served. A file that is unknown, not yours, not\none of those video types, or readable only by a container scope your token lacks is a\n404, the same 404 for all of them. Authorization is the same two-layer check as the\ndownload route: `files:read` at the gate, then the read scope of the file's own container.", "operationId": "filesVideoLink", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of a video in your library (from the gallery list or a finished video job)." } ], "responses": { "200": { "description": "Playback, download and poster links valid for 15 minutes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "mime_type": { "type": "string", "enum": [ "video/mp4", "video/webm", "video/quicktime" ] }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "poster_url": { "type": "string", "nullable": true, "description": "Presigned inline URL for the stored thumbnail. A credential." }, "video_url": { "type": "string", "nullable": true, "description": "Presigned inline URL that plays the video. A credential." }, "download_url": { "type": "string", "nullable": true, "description": "Presigned download URL for the original. A credential." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_in_seconds": { "type": "integer", "nullable": true }, "available": { "type": "boolean" }, "reason": { "type": "string", "nullable": true, "enum": [ "local_only", "link_unavailable", null ] } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, not yours, not a playable video, OR readable only by a container scope your token lacks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:read" } }, "/v1/files/{uuid}/visibility": { "put": { "summary": "Set a file public or private", "description": "An idempotent SET, not a toggle. `public` is REQUIRED and must be a real JSON\nboolean: a missing key, the string \"yes\", the integer 1 and null are all 400s. An\nidempotent set has no defensible default, and guessing one is how a caller publishes\na file it did not mean to publish.\n\nRepeating the call is safe: `changed` reports whether this call was an actual\ntransition, and side effects (the social preview image, the `made_public_at` stamp)\nrun only on a real transition.\n\n**Setting a file public publishes it at a permanent, unauthenticated URL** - see\nGET /v1/files/{uuid}/share.\n\n**Setting a file private is NOT an access control, and must not be described as one.**\nIt removes the public file page. It does NOT revoke access to the bytes: the legacy\n`GET /api/files/serve/{uuid}` and `GET /api/files/thumbnail/{uuid}?original=true`\nroutes serve the same bytes to a caller with NO credentials at all, by deliberate\ndesign - those routes exist so browser tags can load without credentials, and\nthey treat the uuid itself as the capability. Anyone who kept the uuid keeps the\nbytes. Nothing already fetched or cached is retroactively unpublished either. Treat\na file uuid you have ever made public as public forever.", "operationId": "setFileVisibility", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of an item in your library (from the gallery or library list, or a finished job)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public": { "type": "boolean", "description": "true publishes the file, false unpublishes the page. Must be a real boolean." } }, "required": [ "public" ] } } } }, "responses": { "200": { "description": "The resulting state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "file_uuid": { "type": "string", "format": "uuid" }, "public": { "type": "boolean", "description": "The state after this call." }, "made_public_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Stamped on the FIRST transition to public only, so a repeat call leaves it unchanged." }, "changed": { "type": "boolean", "description": "false when the file was already in the requested state." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "`public` missing, or not a real boolean.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:write" } }, "/v1/files/{uuid}/share": { "get": { "summary": "Read the public share URL of a file", "description": "A READ. It returns the URL of an already-public file; it does not publish anything.\nMake the file public first with PUT /v1/files/{uuid}/visibility, or this answers 409.\n\n**The returned URL is PERMANENT, UNAUTHENTICATED and has NO EXPIRY.** It is not a\nsigned link and it carries no token. Anyone who receives it - forwarded, scraped,\nlogged, pasted into a chat - can fetch the file, with no credentials, indefinitely.\n**Handing this URL to anyone is publishing the file.**\n\nDo not confuse it with the presigned URL that GET /v1/files/{uuid}/download returns.\nThose two look superficially similar and are opposites: one expires in an hour, this\none never does.\n\nSetting the file private again removes the public file page but does NOT retroactively\nunpublish bytes already fetched or cached, and does not stop the legacy serve and\nthumbnail routes. The same three facts are returned as DATA below - `is_permanent`,\n`requires_authentication`, `expires_at` - so a caller that never reads prose still\ngets them.\n\nThe share-count beacon that the web app posts is deliberately NOT exposed on this\nAPI: it is unauthenticated product analytics and exposing it would hand a token\nholder a counter to inflate.", "operationId": "getFileShareUrl", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of an item in your library (from the gallery or library list, or a finished job)." } ], "responses": { "200": { "description": "The share URL, with its properties stated as data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "share_url": { "type": "string", "description": "Permanent, unauthenticated URL." }, "is_permanent": { "type": "boolean", "enum": [ true ], "description": "Always true." }, "requires_authentication": { "type": "boolean", "enum": [ false ], "description": "Always false." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Always null. There is no expiry." }, "warning": { "type": "string", "description": "The same warning in one sentence." }, "affiliate_code": { "type": "string", "nullable": true, "description": "Appended to the URL as ?ref= when present." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The file is private and therefore has no share URL. The message names the exact call that fixes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:read" } }, "/v1/files": { "get": { "summary": "List your video, audio and image files", "description": "Newest first. Video and audio items carry `media` (duration, size, frame rate, codecs,\naudio track); it is `null` for images, and its fields are `null` while a file is not\nprobed yet. For a token, items in a container it cannot read are left out of the page.", "operationId": "filesList", "tags": [ "Files" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "video, audio, image, or a comma list of them. Default: all three." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "One page of files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FileListItem" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Page size." }, "offset": { "type": "integer", "description": "Offset." }, "total": { "type": "integer", "description": "Matching files." }, "has_more": { "type": "boolean", "description": "Whether a further page exists." } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Unknown type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:read" } }, "/v1/files/{uuid}/media-url": { "get": { "summary": "Get a one-hour link to read one of your media files", "description": "For video, audio and raster images. `url` is a presigned GET valid one hour that supports\nHTTP range requests, so a player or decoder can read only the parts it needs. **The URL is\na credential for that hour**: do not log it or pass it on. Ask again when it expires.\nA file stored only on the server disk answers with the session serve path and\n`expires_at: null`. Unknown, foreign, other file types and files in a container your\ntoken cannot read are the same 404. Free.", "operationId": "filesMediaUrl", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of a video, audio or image in your library." } ], "responses": { "200": { "description": "The link.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "Presigned GET URL (a credential), or the serve path for a server-disk file." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, not yours, not media, OR readable only by a container scope your token lacks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The link could not be created right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:read" } }, "/v1/files/{uuid}/waveform": { "get": { "summary": "Get the stored waveform peaks of an audio or video file", "description": "Peaks a browser computed and stored with PUT. `peaks` is base64 of `buckets` (min, max)\npairs of signed bytes (format `i8mm`, value / 127 gives -1..1). Answers with an ETag and\nhonours If-None-Match (304). Unknown, foreign, non-media and container-denied files are\nthe same 404 as a file with no waveform yet.", "operationId": "filesWaveform", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of a video or audio file in your library." } ], "responses": { "200": { "description": "The peaks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "buckets": { "type": "integer", "description": "Number of (min, max) pairs." }, "format": { "type": "string", "description": "Always \"i8mm\"." }, "version": { "type": "integer", "description": "Always 1." }, "peaks": { "type": "string", "description": "Base64 of 2 x buckets signed bytes." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "304": { "description": "Unchanged since the ETag in If-None-Match." }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No waveform stored, or unknown file, not yours, not media, OR readable only by a container scope your token lacks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:read" }, "put": { "summary": "Store waveform peaks for an audio or video file", "description": "Safe to repeat. A body with more buckets than the stored waveform replaces it; any other\nleaves it as it is (`stored: false`). `buckets` is at most 100 per second of the file's\nprobed duration (at least 256, at most 60000). An all-zero waveform is refused.", "operationId": "filesPutWaveform", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The file uuid of a video or audio file in your library." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "description": "Must be \"i8mm\"." }, "version": { "type": "integer", "description": "Optional; 1." }, "buckets": { "type": "integer", "description": "Number of (min, max) pairs." }, "peaks": { "type": "string", "description": "Base64 of 2 x buckets signed bytes, each -127..127." } }, "required": [ "format", "buckets", "peaks" ] } } } }, "responses": { "200": { "description": "The waveform now on file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "buckets": { "type": "integer", "description": "Resolution of the stored waveform." }, "stored": { "type": "boolean", "description": "Whether this call wrote it." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid format, bucket count or peaks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, not yours, not media, OR readable only by a container scope your token lacks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The file has no sound.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:write" } }, "/v1/uploads": { "post": { "summary": "Start a resumable upload (up to 2 GB)", "description": "The file goes straight to object storage in parts of `part_size` bytes (8 MB; the last\npart is smaller). Then: ask for part URLs with POST /v1/uploads/{uuid}/parts, PUT each\npart to its URL and keep the `ETag` response header, then POST /v1/uploads/{uuid}/complete.\nAn unfinished upload expires after 24 hours.\n\nWith `sha256` of a file already in your library, nothing is uploaded: `upload_id` is\nnull and `existing_file_uuid` names that file.\n\nTypes: video/mp4, video/quicktime, video/webm, video/x-matroska, video/mpeg, audio/mpeg, audio/wav, audio/mp4, audio/aac, audio/ogg, audio/webm, audio/flac, image/png, image/jpeg, image/webp, image/gif. Images up to\n25 MB, video and audio up to 2 GB. After completion the content is\nchecked; a file that is not what it claims is deleted and the upload fails.", "operationId": "uploadsCreate", "tags": [ "Files" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "Display name of the file." }, "size": { "type": "integer", "description": "Size in bytes." }, "mime_type": { "type": "string", "description": "The file type. Empty: taken from the file extension." }, "sha256": { "type": "string", "description": "Optional hex digest, for dedupe against your library." }, "purpose": { "type": "string", "description": "What the file is for.", "enum": [ "library", "transcription", "studio", "studio_export" ], "default": "library" } }, "required": [ "filename", "size" ] } } } }, "responses": { "201": { "description": "The upload, or the existing file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "upload_id": { "type": "string", "format": "uuid", "nullable": true }, "part_size": { "type": "integer", "description": "Bytes per part." }, "parts": { "type": "integer", "description": "Number of parts." }, "expires_at": { "type": "string", "format": "date-time" }, "existing_file_uuid": { "type": "string", "format": "uuid", "description": "Only when sha256 matched a file you already have." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid filename, size, sha256 or purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "File too large for its type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Unsupported file type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many uploads in progress, or the daily upload limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Uploads are not available right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:write" } }, "/v1/uploads/{uuid}": { "delete": { "summary": "Cancel a resumable upload", "description": "Discards the parts uploaded so far. Cancelling an already cancelled or expired upload succeeds.", "operationId": "uploadsAbort", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "upload_id from POST /v1/uploads." } ], "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "upload_id": { "type": "string", "description": "The upload." }, "aborted": { "type": "boolean", "description": "Always true." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown upload, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The upload is being completed or already completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:write" } }, "/v1/uploads/{uuid}/parts": { "post": { "summary": "Get upload URLs for parts", "description": "Presigned PUT URLs, valid 15 minutes, for up to 100 part numbers per call.\nPUT the part bytes to the URL as they are (no form encoding) and keep the `ETag` response\nheader for complete. **The URLs are credentials**: do not log them.", "operationId": "uploadsParts", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "upload_id from POST /v1/uploads." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "part_numbers": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 100, "description": "Part numbers, 1 to parts." } }, "required": [ "part_numbers" ] } } } }, "responses": { "200": { "description": "One URL per part number.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "urls": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Part number => presigned PUT URL." }, "expires_at": { "type": "string", "format": "date-time" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid part numbers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown upload, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The upload is no longer open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "The upload expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:write" } }, "/v1/uploads/{uuid}/complete": { "post": { "summary": "Finish a resumable upload", "description": "Joins the parts, checks the size and the content, and adds the file to your library.\nVideo and audio come back with `media` filled in. Repeating a complete that succeeded\nreturns the same file.", "operationId": "uploadsComplete", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "upload_id from POST /v1/uploads." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "part_number": { "type": "integer", "description": "1 to parts." }, "etag": { "type": "string", "description": "The ETag header the PUT returned." } }, "required": [ "part_number", "etag" ] }, "description": "Every part, once." } }, "required": [ "parts" ] } } } }, "responses": { "200": { "description": "The file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "file_uuid": { "type": "string", "format": "uuid" }, "file": { "$ref": "#/components/schemas/FileListItem" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid parts list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold files:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown upload, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Parts are missing on the storage side, or the upload is not open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "The upload expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Size or content does not match; the file was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Storage not reachable; try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "files:write" } }, "/v1/audio/transcribe": { "post": { "summary": "Transcribe an audio file you own (async)", "description": "Starts an asynchronous transcription of audio (or a video's sound track) already\nstored in your library. Upload it first with POST /v1/uploads (up to 2 GB) or\nPOST /v1/files/upload (up to 48 MB) and pass the `file_uuid` it returns.\n\n**TWO DIFFERENT SCOPES ARE INVOLVED, and this is deliberate (D-15-07).**\nSubmitting needs `audio:write`. READING THE RESULT NEEDS `text:read`, because a\ntranscript is text: both GET /v1/transcriptions/{uuid} and GET /v1/jobs/{id}\nclassify this work into the `text` container.\n\n**A token holding only `audio:write` can start this job, be charged for it, and then\nnever be able to read the transcript** - the status poll and the transcript read both\nanswer 404. Mint a token holding `audio:write` AND `text:read` for a complete\nworkflow. The 202 body repeats this warning.", "operationId": "transcribeAudio", "tags": [ "Audio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_uuid": { "type": "string", "format": "uuid", "description": "An audio or video file you own." }, "language": { "type": "string", "description": "Optional language hint, e.g. \"de\" or \"en-US\", or \"auto\" to detect it." }, "diarize": { "type": "boolean", "description": "Speaker separation. Must be a real boolean. Default false." }, "refinement_type": { "type": "string", "enum": [ "raw", "refined", "summary", "conclusions", "devils_advocate", "action_points" ], "default": "raw", "description": "What to produce beyond the raw transcript." }, "source_file_uuid": { "type": "string", "format": "uuid", "description": "The library file this transcript belongs to when file_uuid is audio taken from it (e.g. a video's sound track). Defaults to file_uuid." }, "reuse": { "type": "boolean", "description": "true: when the source file already has a finished transcript with timing (or one still running), answer 200 with it and charge nothing." } }, "required": [ "file_uuid" ] } } } }, "responses": { "202": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "transcription_uuid": { "type": "string", "format": "uuid", "description": "Read it with GET /v1/transcriptions/{uuid} - which needs text:read." }, "job_id": { "type": "integer", "description": "Poll with GET /v1/jobs/{id} - which also needs text:read for this job." }, "estimated_cost": { "type": "number", "format": "float", "description": "Estimated credits." }, "status": { "type": "string", "example": "pending" }, "note": { "type": "string", "description": "Restates the two-scope split in the body itself." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "200": { "description": "reuse: true and the source file already has a transcript; nothing was charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "transcription_uuid": { "type": "string", "format": "uuid" }, "job_id": { "type": "integer", "nullable": true }, "estimated_cost": { "type": "number", "format": "float", "description": "Always 0." }, "status": { "type": "string", "description": "completed | processing | pending" }, "reused": { "type": "boolean", "description": "Always true." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Missing file_uuid, an invalid refinement_type or language, or a non-boolean diarize.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file_uuid, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "The file is neither audio nor video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The audio could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "audio:write" } }, "/v1/transcriptions/{uuid}": { "get": { "summary": "Read a transcript", "description": "**Requires `text:read`, NOT `audio:read`** (D-15-07 / D-08). A transcript is text, so\nit lives in the `text` container even though it was produced from audio. The route\nthat CREATED it requires `audio:write`. This asymmetry is intentional and must not be\n\"fixed\": a complete transcription workflow legitimately needs both scopes.\n\n`transcript` is null until `status` is `completed`. A uuid belonging to another\naccount answers 404, identical to an unknown uuid - there is no source-based\nexemption on this route.", "operationId": "getTranscription", "tags": [ "Audio" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The transcription_uuid returned when the transcription was started (POST /v1/audio/transcribe). Not the audio file uuid." } ], "responses": { "200": { "description": "The transcription record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "completed | processing | failed | pending" }, "source": { "type": "string", "nullable": true }, "original_filename": { "type": "string", "nullable": true }, "refinement_type": { "type": "string", "nullable": true, "enum": [ "raw", "refined", "summary", "conclusions", "devils_advocate", "action_points" ] }, "transcript": { "type": "string", "nullable": true, "description": "null until status is completed." }, "refined_content": { "type": "string", "nullable": true }, "audio_duration_seconds": { "type": "integer", "nullable": true }, "file_size_bytes": { "type": "integer", "nullable": true }, "credits_charged": { "type": "number", "format": "float", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "segments": { "type": "array", "description": "Sentence or utterance timing, empty for older transcripts. speaker (0-based) only with speaker separation.", "items": { "type": "object", "properties": { "start_ms": { "type": "integer" }, "end_ms": { "type": "integer" }, "text": { "type": "string" }, "speaker": { "type": "integer" } } } }, "words": { "type": "array", "nullable": true, "description": "Word timing when the provider returned it, else null.", "items": { "type": "object", "properties": { "start_ms": { "type": "integer" }, "end_ms": { "type": "integer" }, "text": { "type": "string" }, "speaker": { "type": "integer" } } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold text:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown transcription, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:read" } }, "/v1/audio/speech": { "post": { "summary": "Turn text into speech", "description": "Speaks the text with the chosen voice and stores the audio as a new file in your library.\nSYNCHRONOUS: the response carries the file. Billed per 1,000 characters of the trimmed text\n(price per quality from `GET /v1/audio/speech/quote`); nothing is charged when the voice\ncannot be generated. The language follows the text.\nQualities: `standard` (OpenAI gpt-4o-mini-tts, takes `instructions`), `studio` (ElevenLabs Multilingual v2).", "operationId": "createSpeech", "tags": [ "Audio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000, "description": "What to say, up to 4000 characters." }, "quality": { "type": "string", "enum": [ "standard", "studio" ], "default": "standard" }, "voice": { "type": "string", "description": "A voice id of the quality (see the quote). Default: its first voice." }, "instructions": { "type": "string", "maxLength": 300, "description": "standard only: how to deliver the text, e.g. \"calm and friendly\"." }, "title": { "type": "string", "maxLength": 200, "description": "Used for the file name. Default: the first words of the text." }, "client_ref": { "type": "string", "description": "Idempotency key: a repeat within 24 h returns the first response and is not charged again." } }, "required": [ "text" ] } } } }, "responses": { "201": { "description": "The stored audio file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "file_uuid": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "mime_type": { "type": "string", "example": "audio/mpeg" }, "duration_ms": { "type": "integer", "nullable": true }, "size_bytes": { "type": "integer", "nullable": true }, "characters": { "type": "integer" }, "credits": { "type": "number", "format": "float", "description": "Credits charged." }, "quality": { "type": "string" }, "voice": { "type": "string" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Missing text, or an unknown quality or voice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold audio:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "A request with this client_ref is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The text is too long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The voice could not be generated; nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "This quality is not available right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "audio:write" } }, "/v1/audio/speech/quote": { "get": { "summary": "Price and voices for text to speech", "description": "The credits `POST /v1/audio/speech` charges for this many characters in each quality, with the voices. Nothing is charged.", "operationId": "quoteSpeech", "tags": [ "Audio" ], "parameters": [ { "name": "characters", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 4000, "default": 0 }, "description": "Characters of the trimmed text." } ], "responses": { "200": { "description": "Prices and voices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "characters": { "type": "integer" }, "max_characters": { "type": "integer" }, "qualities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "available": { "type": "boolean" }, "credits_per_1000": { "type": "number", "nullable": true }, "credits": { "type": "number", "nullable": true }, "instructions": { "type": "boolean" }, "voices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "tone": { "type": "string" }, "sample_url": { "type": "string", "nullable": true } } } } } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "characters is not a whole number up to the maximum.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold audio:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "audio:read" } }, "/v1/transcriptions/by-file/{uuid}": { "get": { "summary": "Find the reusable transcript of a library file", "description": "The newest finished transcript with timing made from this file (or one still running),\nso a caller can show \"no charge\" before transcribing again. Needs `text:read`.\n`transcription` is null when there is none.", "operationId": "findTranscriptionForFile", "tags": [ "Audio" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The library file uuid (the source_file_uuid of POST /v1/audio/transcribe)." } ], "responses": { "200": { "description": "The transcript reference, or null.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "transcription": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "completed | processing | pending" }, "audio_duration_seconds": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold text:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown file, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:read" } }, "/v1/text/generate": { "post": { "summary": "Run a text tool", "description": "Runs one of the tools listed by GET /v1/text/tools against your input text. One\nstateless call; billing is metered on ACTUAL token usage, not a flat rate, and the\nresponse returns the token counts and the cost breakdown it charged on.\n\nThere is deliberately no free-form prompt escape hatch and no prompt-preview route:\nboth would publish internal prompt engineering to any token holder.", "operationId": "generateText", "tags": [ "Text" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool_key": { "type": "string", "description": "A `key` from GET /v1/text/tools." }, "input_text": { "type": "string", "description": "The text the tool operates on." }, "options": { "type": "object", "additionalProperties": true, "description": "Per-tool options." }, "framework_id": { "type": "integer", "description": "Optional StoryBrand framework (integer id) to condition the output on. Must be one you own." }, "source_type": { "type": "string", "description": "Provenance label. Defaults to \"direct\"." }, "source_id": { "type": "integer", "description": "Optional integer id of the source record." }, "source_uuid": { "type": "string", "description": "Optional uuid of the source record." } }, "required": [ "tool_key", "input_text" ] } } } }, "responses": { "200": { "description": "The tool output.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "operation_uuid": { "type": "string", "format": "uuid" }, "tool": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "input": { "type": "string" }, "output": { "type": "string" }, "used_blueprint": { "type": "boolean" }, "credits_used": { "type": "number", "format": "float" }, "processing_time_ms": { "type": "integer" }, "tokens": { "type": "object", "properties": { "input": { "type": "integer" }, "output": { "type": "integer" }, "total": { "type": "integer" } } }, "cost_breakdown": { "type": "object", "properties": { "actual_cost_usd": { "type": "number" }, "credit_cost": { "type": "number" }, "markup_multiplier": { "type": "number" } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Missing tool_key or input_text, or malformed JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such tool. Your key is not echoed back in the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The provider is over quota or overloaded. A fixed sentence - no provider text is relayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/v1/text/enhance-prompt": { "post": { "summary": "Rewrite a rough prompt for an image or video model", "description": "Turns a rough prompt or keywords into a detailed prompt for the named tool.\nUp to four reference images (inline, `{data, mimeType}`) are used as visual context;\nan unusable image is dropped, not refused. Answers synchronously.\n\nBilled by tokens: a hold of 0.01 credits is taken before the model call and the\nactual token cost is charged against it.", "operationId": "enhancePrompt", "tags": [ "Text" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "The rough prompt or keywords." }, "tool_context": { "type": "string", "enum": [ "image-generator", "image-variator", "image-fusion", "video-generator" ], "default": "image-generator", "description": "The model the prompt is for." }, "images": { "type": "array", "maxItems": 4, "items": { "type": "object", "properties": { "data": { "type": "string", "description": "Base64 or a data URL." }, "mimeType": { "type": "string", "description": "The image type, used when `data` is plain base64." } } }, "description": "Optional reference images." } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "The rewritten prompt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "enhanced_prompt": { "type": "string", "description": "The rewritten prompt." }, "credits_used": { "type": "number", "format": "float", "description": "Credits charged." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "The prompt is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/v1/generations/pending": { "get": { "summary": "List your generations that are still running", "description": "Generations with status `generating` started in the last 30 minutes, newest first.\nFree and read only. A token sees only the generations whose container it can read\n(the same rule as `GET /v1/jobs/{id}`), so this any-of read scope is a pre-filter.", "operationId": "pendingGenerations", "tags": [ "Jobs" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "description": "Only this generation type, e.g. `image_variation` or `background_removal`." } ], "responses": { "200": { "description": "The running generations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "generations": { "type": "array", "items": { "type": "object", "properties": { "generation_id": { "type": "integer" }, "uuid": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string", "nullable": true }, "credits_used": { "type": "number" }, "created_at": { "type": "string" }, "input_data": { "type": "object", "additionalProperties": true } } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "`type` is not a generation type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token holds none of images:read, videos:read, audio:read, text:read, files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": [ "images:read", "videos:read", "audio:read", "text:read", "files:read" ] } }, "/v1/images/upscale-providers": { "get": { "summary": "List the upscale providers and their prices", "description": "The providers `POST /v1/images/upscale` accepts, each with its scales, output limit\nand the credits per scale (`scale_credits`), plus the default provider. Free.", "operationId": "upscaleProviders", "tags": [ "Images" ], "responses": { "200": { "description": "The providers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "scales": { "type": "array", "items": { "type": "integer" } }, "scale_credits": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "default_provider": { "type": "string" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:read" } }, "/v1/images/photoshoot": { "post": { "summary": "Generate one photo for an AI photoshoot (sync)", "description": "Creates one new photo in the style of the reference images. `images` are base64\nstrings: the first is the blueprint, used only for the aspect ratio; the others are\nstyle references. `changeOptions` names what may change (e.g. `Background`, `Pose`;\n`Character` allows changing the subjects). Answers when the image is ready.", "operationId": "photoshootImage", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "images": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Base64 images: the blueprint first, then style references." }, "changeOptions": { "type": "array", "items": { "type": "string" }, "description": "What the new photo may change." }, "variety": { "type": "string", "enum": [ "Subtle", "Creative", "Diverse", "Experimental" ], "default": "Creative", "description": "How far the new photo may stray." }, "prompt": { "type": "string", "description": "Optional request for the new photo." } }, "required": [ "images", "changeOptions" ] } } } }, "responses": { "200": { "description": "The generated photo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true, "properties": { "image": { "type": "string", "description": "The image, as a data URL or a download path." }, "download_url": { "type": "string", "nullable": true }, "file_uuid": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "generation_id": { "type": "integer" }, "credits_used": { "type": "number" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "No images, no changeOptions, or an unusable image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The request was blocked by the model's content policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "images:write" } }, "/v1/text/tools": { "get": { "summary": "List the available text tools", "description": "The tool registry, flat and grouped by category. This is the discovery route for POST /v1/text/generate: every `tool_key` it accepts appears here.", "operationId": "listTextTools", "tags": [ "Text" ], "responses": { "200": { "description": "The registry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Each entry carries at least tool_key, tool_name and category." }, "by_category": { "type": "object", "additionalProperties": true, "description": "The same tools, keyed by category." }, "categories": { "type": "array", "items": { "type": "string" } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold text:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:read" } }, "/v1/library": { "get": { "summary": "List library items (transcriptions, uploads, documents)", "description": "The Library view: the things the gallery does not cover. Items are filtered to the\ncontainers your token can read. A token holding no readable container gets an empty\nlist with a 200, never a 403 - the route gate already ran and this is a view filter,\nnot an access denial.\n\n`counts` holds the real totals of your library per item type, independent of `limit`,\n`offset` and `type`. It only counts items in containers your token can read, so it cannot\nleak the existence of the others. `pagination.has_more` tells whether more items follow\nthis page, measured BEFORE container filtering. With `type=all` the three item types are\nmerged, newest change first, and paged as one list.\n\nThe route-level scope is an any-of list (`text:read`, `audio:read`, `files:read`) and\nis a coarse pre-filter, not the boundary. The per-item container check is.", "operationId": "listLibrary", "tags": [ "Library" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "transcription", "upload", "document" ], "default": "all" }, "description": "Anything else is a 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Clamped, not rejected." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "The filtered page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "counts": { "type": "object", "additionalProperties": true, "description": "Real totals per item type (total, transcriptions, uploads, documents), limited to the containers the token can read." }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid `type`. The message lists the valid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token holds none of text:read, audio:read, files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": [ "text:read", "audio:read", "files:read" ] } }, "/v1/account/credits": { "get": { "summary": "Get your credit balance and recent credit activity", "description": "Built for the MCP `show_credits` tool. This call is free and read only: it never charges,\nreserves or initializes credits. It carries no links, so unlike the gallery and video\nroutes nothing in it expires after 15 minutes.\n\n- `balance` holds available, reserved, lifetime purchased and lifetime used credits. An\n account with no credit record yet reads as all zeros.\n- `transactions` lists the newest `limit` ledger entries. Usage amounts are negative.\n Each entry carries only uuid, type, amount, balance_after, description and created_at;\n adjustment and referral entries carry a fixed label instead of their stored text.\n\nCredits belong to no content container, so any one read scope (`images:read`,\n`videos:read`, `audio:read`, `text:read` or `files:read`) admits this route.", "operationId": "accountCredits", "tags": [ "Account" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 }, "description": "Recent ledger entries to return. Larger values are clamped; a non-integer is a 400." } ], "responses": { "200": { "description": "The balance and the newest ledger entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "balance": { "type": "object", "properties": { "available": { "type": "number" }, "reserved": { "type": "number" }, "lifetime_purchased": { "type": "number" }, "lifetime_used": { "type": "number" } } }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": "number" }, "balance_after": { "type": "number" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } } }, "limit": { "type": "integer" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "`limit` is not an integer from 1 to 25.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token holds none of images:read, videos:read, audio:read, text:read, files:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": [ "images:read", "videos:read", "audio:read", "text:read", "files:read" ] } }, "/v1/storybrand": { "post": { "summary": "Create a StoryBrand framework", "description": "Creates an empty seven-step framework. Costs NO credits: the initial message it returns is a template, not a model call. Fill the steps with PUT /v1/storybrand/{uuid}/step/{n}, then call POST /v1/storybrand/{uuid}/generate.", "operationId": "createStoryBrand", "tags": [ "StoryBrand" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Optional name for the framework." }, "business_name": { "type": "string", "description": "Optional." }, "industry": { "type": "string", "description": "Optional." }, "target_audience": { "type": "string", "description": "Optional." } } } } } }, "responses": { "200": { "description": "The created framework.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "framework": { "type": "object", "additionalProperties": true } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Malformed body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" }, "get": { "summary": "List your StoryBrand frameworks", "description": "Optionally filtered by status.", "operationId": "listStoryBrand", "tags": [ "StoryBrand" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional status filter." } ], "responses": { "200": { "description": "Your frameworks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "frameworks": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold text:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:read" } }, "/v1/storybrand/steps": { "get": { "summary": "The static seven-step configuration", "description": "The step definitions themselves - what each of the seven steps is for. Static; not per-framework. Use it to drive PUT /v1/storybrand/{uuid}/step/{n}.", "operationId": "getStoryBrandSteps", "tags": [ "StoryBrand" ], "responses": { "200": { "description": "The step configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold text:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:read" } }, "/v1/storybrand/{uuid}": { "get": { "summary": "Read a StoryBrand framework", "description": "A framework belonging to another account answers 404, identical to an unknown uuid - a 403 there would be an existence oracle.", "operationId": "getStoryBrand", "tags": [ "StoryBrand" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The StoryBrand framework uuid, as returned when it was created or listed." } ], "responses": { "200": { "description": "The framework.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "framework": { "type": "object", "additionalProperties": true } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown framework, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:read" }, "patch": { "summary": "Update framework metadata", "description": "Metadata only - the title and the business name. Step CONTENT is written with PUT /v1/storybrand/{uuid}/step/{n}.", "operationId": "updateStoryBrand", "tags": [ "StoryBrand" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The StoryBrand framework uuid, as returned when it was created or listed." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New title." }, "business_name": { "type": "string", "description": "New business name." } } } } } }, "responses": { "200": { "description": "The updated framework.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "framework": { "type": "object", "additionalProperties": true } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Malformed body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown framework, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" }, "delete": { "summary": "Delete a StoryBrand framework", "description": "Soft delete.", "operationId": "deleteStoryBrand", "tags": [ "StoryBrand" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The StoryBrand framework uuid, as returned when it was created or listed." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "message": { "type": "string" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown framework, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/v1/storybrand/{uuid}/step/{n}": { "put": { "summary": "Write one step of a framework", "description": "**Text only, no model call and no credit cost.** This is the only way a\nnon-interactive caller can fill the seven steps: the conversational refine and chat\nsub-steps carry session state and are deliberately not on this API.\n\n`n` must be numeric; a non-numeric step segment is a 404 from the router and never\nreaches the handler.", "operationId": "updateStoryBrandStep", "tags": [ "StoryBrand" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The StoryBrand framework uuid, as returned when it was created or listed." }, { "name": "n", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Step number, 1 to 7. See GET /v1/storybrand/steps." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The step text." } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "The updated step.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Missing content, or malformed body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown framework, not yours, or a step number that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/v1/storybrand/{uuid}/generate": { "post": { "summary": "Generate the StoryBrand output (billed)", "description": "The payoff, and the ONLY billed operation in this group. Requires the framework to be 100% complete, which is what PUT /v1/storybrand/{uuid}/step/{n} exists to make reachable without a conversation.", "operationId": "generateStoryBrand", "tags": [ "StoryBrand" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The StoryBrand framework uuid, as returned when it was created or listed." } ], "responses": { "200": { "description": "The generated output.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "The framework is not complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown framework, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/v1/documents": { "post": { "summary": "Create a Flow document", "description": "Costs NO credits: the `initial_message` it returns is a template, not a model call. A `storybrand_framework_id` you do not own is a 400.", "operationId": "createDocument", "tags": [ "Documents" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Optional." }, "content": { "type": "string", "description": "Optional initial content." }, "document_type": { "type": "string", "description": "Optional document type." }, "project_id": { "type": "integer", "description": "Optional project to file it under." }, "storybrand_framework_id": { "type": "integer", "description": "Optional StoryBrand framework (integer id) you own." } } } } } }, "responses": { "201": { "description": "The created document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "document": { "type": "object", "additionalProperties": true }, "session_uuid": { "type": "string", "format": "uuid" }, "framework": { "type": "object", "nullable": true, "additionalProperties": true }, "initial_message": { "type": "string", "description": "Template text. Not a model call." } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Malformed body, or a framework you do not own.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" }, "get": { "summary": "List your Flow documents", "description": "Optionally filtered by document_type and status.", "operationId": "listDocuments", "tags": [ "Documents" ], "parameters": [ { "name": "document_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Your documents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The token does not hold text:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:read" } }, "/v1/documents/{uuid}": { "get": { "summary": "Read a Flow document", "description": "Returns the document, its chat session with system messages filtered out, and a sanitised subset of any linked StoryBrand framework. A document belonging to another account answers 404, identical to an unknown uuid.", "operationId": "getDocument", "tags": [ "Documents" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The document uuid, as returned when it was created or listed." } ], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "document": { "type": "object", "additionalProperties": true }, "session": { "type": "object", "nullable": true, "additionalProperties": true }, "framework": { "type": "object", "nullable": true, "additionalProperties": true } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown document, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:read" }, "put": { "summary": "Write a Flow document", "description": "The full write. This is the non-interactive substitute for the editor autosave, which is deliberately not on this API - it is the same ownership check and the same model.", "operationId": "updateDocument", "tags": [ "Documents" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The document uuid, as returned when it was created or listed." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New title." }, "content": { "type": "string", "description": "New content." }, "status": { "type": "string", "description": "New status." } } } } } }, "responses": { "200": { "description": "The updated document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "document": { "type": "object", "additionalProperties": true } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Malformed body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown document, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" }, "delete": { "summary": "Delete a Flow document", "operationId": "deleteDocument", "tags": [ "Documents" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The document uuid, as returned when it was created or listed." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "message": { "type": "string" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown document, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/v1/documents/{uuid}/generate-title": { "post": { "summary": "Derive and store a title from the content", "description": "**A LOCAL HEURISTIC, not a model call: no provider, no credits.** It takes the first meaningful line of the content, strips a markdown heading marker and truncates at 60 characters. It requires `text:write` because it PERSISTS the derived title, not because it bills.", "operationId": "generateDocumentTitle", "tags": [ "Documents" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The document uuid, as returned when it was created or listed." } ], "responses": { "200": { "description": "The derived title.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "title": { "type": "string" } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown document, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/v1/documents/{uuid}/link-framework": { "post": { "summary": "Link a StoryBrand framework to a document", "description": "`framework_id` is the framework's INTEGER primary key, not its uuid. Ownership is checked on BOTH sides; a framework you do not own answers 400, not 404.", "operationId": "linkDocumentFramework", "tags": [ "Documents" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The document uuid, as returned when it was created or listed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "framework_id": { "type": "integer", "description": "Integer primary key of a StoryBrand framework you own. NOT its uuid." } }, "required": [ "framework_id" ] } } } }, "responses": { "200": { "description": "Linked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Missing framework_id, or a framework you do not own.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown document, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/v1/documents/{uuid}/unlink-framework": { "post": { "summary": "Unlink the StoryBrand framework from a document", "description": "Returns the updated document, so the cleared link is visible without a second read.", "operationId": "unlinkDocumentFramework", "tags": [ "Documents" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The document uuid, as returned when it was created or listed." } ], "responses": { "200": { "description": "Unlinked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "document": { "type": "object", "additionalProperties": true } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown document, or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "text:write" } }, "/files/download/{uuid}": { "get": { "summary": "Download a file (legacy path)", "description": "The OLDER download path, kept because existing callers and the product's own file\nflows use it. It accepts the same Bearer token.\n\n**It does NOT authorize the same way as `GET /v1/files/{uuid}/download`, and the\ndifference is stated here rather than left to be discovered.** This route is\nowner-checked but carries NO SCOPE CHECK AT ALL: any valid token belonging to the\nowner is served the file, including one holding neither `files:read` nor the\nfile's container read scope. The `/v1/` route requires both. Prefer the `/v1/`\nroute; this one is documented for accuracy, not recommended.\n\nThis is the only non-`/v1/` path in this document.", "operationId": "downloadFile", "tags": [ "Files" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Binary image file", "content": { "image/png": [], "image/jpeg": [], "image/webp": [] } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "tags": [ { "name": "Images", "description": "Image generation, upscaling and the image sub-tools" }, { "name": "Videos", "description": "Video generation and merging" }, { "name": "Audio", "description": "Transcription. Note the two-scope split: submitting needs audio:write, reading the transcript needs text:read" }, { "name": "Text", "description": "Text tools and their registry" }, { "name": "StoryBrand", "description": "StoryBrand frameworks, non-interactive subset" }, { "name": "Documents", "description": "Flow documents, non-interactive subset" }, { "name": "Gallery", "description": "Generated items" }, { "name": "Library", "description": "Transcriptions, uploads and documents" }, { "name": "Jobs", "description": "Async job status polling" }, { "name": "Files", "description": "Upload, download, delete, visibility and sharing" }, { "name": "Meta", "description": "API discovery" }, { "name": "Account", "description": "Credit balance and credit activity, read only" } ], "x-breaking-changes": [ { "id": "gallery-item-identity", "decision": "D-07", "shipped_in": "Phase 14", "summary": "GalleryItem.uuid is the FILE uuid, not the generation uuid.", "detail": "The `uuid` field of every gallery item used to be the generation uuid. It is now the uuid of the FILE the generation produced - the identifier the download and file routes actually take. The generation uuid is still returned, under the new `generation_uuid` field, so nothing was removed.", "migration": "If you stored gallery `uuid` values to correlate with generations, read `generation_uuid` instead. If you used them to download, no change is needed - that now works, and previously did not.", "aliased": false }, { "id": "gallery-category-vocabulary", "decision": "D-07b / D-15-28", "shipped_in": "Phase 14, alias added in Phase 15", "summary": "The `category` vocabulary moved from singular to the plural container names.", "detail": "Item payloads report images|videos|audio|text|files - the same vocabulary as the read scopes - where they used to report image|video|text|other. For one release the `?category=` FILTER also accepts the deprecated singular image|video, answering with a `Deprecation: true` response header. Responses always carry the plural. `text` is spelled identically in both vocabularies and is not a deprecation.", "migration": "Send the plural. The singular aliases are removed in a later release with a changelog note; the `Deprecation` header tells you if you are still relying on them.", "aliased": true, "aliases": { "image": "images", "video": "videos", "text": "text" } }, { "id": "error-code-is-an-integer", "decision": "15-16 / TOKEN-08", "shipped_in": "Phase 15", "summary": "`error.code` is always the integer HTTP status; the machine-readable string moved to `error.type`.", "detail": "Three 401 bodies used to put a STRING in `error.code`: `token_expired`, `token_revoked`, `token_invalid`. Every other error put the integer status there, which left `code` a field no client could type. All three identifiers are preserved byte-identically and now live in the new, always-present `error.type`; `error.code` is the integer 401.", "migration": "Rename the key: branch on `error.type` instead of `error.code`. A client that still compares `error.code` to one of the three strings gets false - a wrong branch, not an exception.", "aliased": false }, { "id": "insufficient-credits-is-402", "decision": "COMM-10", "shipped_in": "2026-10-09", "summary": "Running out of credits is always HTTP 402 with `error.type` `insufficient_credits`.", "detail": "Some generation endpoints answered an insufficient balance with 422, the same status as a validation error. Every endpoint now answers 402 `insufficient_credits`, and adds `required_credits` and `available_credits` when they are known. 422 now means only that the request itself was invalid.", "migration": "If you detect a missing balance by status 422, check for 402 (or `error.type` `insufficient_credits`) instead. Retrying a 402 does not help until credits are added.", "aliased": false }, { "id": "remove-background-is-async", "decision": "COMM-20", "shipped_in": "2026-10-09", "summary": "POST /v1/images/remove-background queues a job and answers 202, like the other generation routes.", "detail": "The route used to run the removal inside the request and answer 200 with `file_uuid`, `download_url`, `mime_type`, `generation_id`, `credits_used` and `processing_time_ms`. It now answers 202 with `job_id`, `generation_id`, `generation_uuid`, `status` and `estimated_credits`; the new file appears in the result of `GET /v1/jobs/{id}` once the job is completed. The credits are reserved when the job is queued and charged when it succeeds. It also accepts the image inline (`image_data`) as well as by `file_uuid`.", "migration": "Treat the call like images/vary: read `job_id` from the 202, poll `GET /v1/jobs/{id}` until `status` is `completed` or `failed`, then take `file_uuid` and `download_url` from `result`. A client that reads `data.file_uuid` from the start response gets nothing.", "aliased": false } ], "x-curl-examples": { "generate": "curl -X POST https://contentmaschine.ai/api/v1/images/generate \\\n -H \"Authorization: Bearer sk-cm-YOUR_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"prompt\":\"A serene mountain lake\",\"model\":\"standard\",\"aspect_ratio\":\"16:9\"}'", "poll": "curl https://contentmaschine.ai/api/v1/jobs/123 \\\n -H \"Authorization: Bearer sk-cm-YOUR_KEY\"", "transcribe": "curl -X POST https://contentmaschine.ai/api/v1/audio/transcribe \\\n -H \"Authorization: Bearer sk-cm-YOUR_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"file_uuid\":\"UUID\",\"language\":\"de\"}'\n# the token needs audio:write to submit AND text:read to read the transcript back", "discover": "curl https://contentmaschine.ai/api/v1/openapi.json\n# no Authorization header: this route and /api/v1/models are public", "download": "curl -o image.png \"https://contentmaschine.ai/api/files/download/UUID\" \\\n -H \"Authorization: Bearer sk-cm-YOUR_KEY\"" } }