{ "openapi": "3.1.0", "info": { "title": "Sirv AI Studio API", "description": "AI-powered image, video, and commerce-creative processing endpoints for Sirv AI Studio.", "version": "1.0.0", "contact": { "name": "Sirv AI Studio", "url": "https://www.sirv.studio" } }, "servers": [ { "url": "https://www.sirv.studio", "description": "Production server" } ], "tags": [ { "name": "Account", "description": "Authenticated account and usage endpoints." }, { "name": "AI 3D tools", "description": "AI 3D tools endpoints." }, { "name": "AI image tools", "description": "Image processing, generation, editing, and commerce-creative endpoints." }, { "name": "AI text tools", "description": "Text generation and product-copy endpoints." }, { "name": "AI video tools", "description": "Video generation and motion endpoints." }, { "name": "Assets", "description": "Asset library endpoints for DAM search, metadata, and bulk operations." }, { "name": "Products", "description": "Product catalog endpoints for PIM search, assets, and bulk operations." }, { "name": "Zapier automation", "description": "Automation endpoints used by Zapier, n8n, and compatible workflow tools." } ], "paths": { "/api/zapier/me": { "get": { "description": "Verify a Zapier or compatible automation API key and return the authenticated user profile used for connector authentication tests.", "operationId": "zapierGetAuthenticatedUser", "responses": { "200": { "description": "Authenticated Zapier user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierAuthenticatedUserResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "zapierApiKey": [] } ], "summary": "Get authenticated Zapier user", "tags": [ "Zapier automation" ] } }, "/api/zapier/sirv/search": { "post": { "description": "Search files in the connected Sirv account using Sirv search syntax for Zapier and automation workflows.", "operationId": "zapierSirvSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "from": { "type": "integer", "minimum": 0, "maximum": 1000 }, "size": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 }, "sort_field": { "type": "string", "enum": [ "filename.raw", "basename.raw", "dirname.raw", "contentType.raw", "mtime", "ctime", "size" ] }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully searched Sirv files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSirvSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/WorkspaceCapabilityRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "zapierApiKey": [] } ], "summary": "Search Sirv files", "tags": [ "Zapier automation" ] } }, "/api/zapier/sirv/get-metadata": { "post": { "description": "Fetch reviewed metadata fields and file information for one file in the connected Sirv account.", "operationId": "zapierSirvGetMetadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_path": { "type": "string", "minLength": 1 } }, "required": [ "file_path" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully fetched Sirv file metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSirvGetMetadataResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/WorkspaceCapabilityRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "zapierApiKey": [] } ], "summary": "Get Sirv file metadata", "tags": [ "Zapier automation" ] } }, "/api/zapier/sirv/file": { "post": { "description": "Queue a Sirv file rename, copy, or delete operation for the connected workspace account.", "operationId": "zapierSirvFile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "rename", "copy", "delete" ] }, "file_path": { "type": "string", "minLength": 1 }, "target_path": { "type": "string", "minLength": 1 } }, "required": [ "action", "file_path" ], "additionalProperties": false, "anyOf": [ { "properties": { "action": { "const": "delete" } }, "required": [ "action", "file_path" ] }, { "required": [ "action", "file_path", "target_path" ] } ] } } } }, "responses": { "200": { "description": "Successfully queued Sirv file operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSirvFileOperationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/WorkspaceCapabilityRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "zapierApiKey": [] } ], "summary": "Queue Sirv file operation", "tags": [ "Zapier automation" ] } }, "/api/zapier/sirv/folder": { "post": { "description": "Create a Sirv folder or list folder contents in the connected workspace account.", "operationId": "zapierSirvFolder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "list" ] }, "folder_path": { "type": "string", "minLength": 1 }, "continuation": { "type": "string", "minLength": 1 } }, "required": [ "action", "folder_path" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully performed Sirv folder operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSirvFolderOperationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/WorkspaceCapabilityRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "zapierApiKey": [] } ], "summary": "Perform Sirv folder operation", "tags": [ "Zapier automation" ] } }, "/api/zapier/sirv/upload": { "post": { "description": "Fetch a remote file URL into the connected Sirv account for Zapier and automation workflows.", "operationId": "zapierSirvUpload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri", "maxLength": 1024 }, "filename": { "type": "string", "minLength": 1, "maxLength": 1024 }, "folder": { "type": "string", "default": "/ai-tools", "minLength": 0, "maxLength": 1024 }, "target_path": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully uploaded remote file to Sirv", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSirvUploadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/WorkspaceCapabilityRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "zapierApiKey": [] } ], "summary": "Upload remote file to Sirv", "tags": [ "Zapier automation" ] } }, "/api/zapier/sirv/metadata": { "post": { "description": "Queue a Sirv file metadata update for the connected workspace account.", "operationId": "zapierSirvMetadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_path": { "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 1024 }, "title": { "type": "string", "maxLength": 256 }, "tags": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "product": { "type": "object", "minProperties": 1, "properties": { "id": { "type": "string", "maxLength": 256 }, "name": { "type": "string", "maxLength": 256 }, "brand": { "type": "string", "maxLength": 256 }, "category1": { "type": "string", "maxLength": 256 }, "category2": { "type": "string", "maxLength": 256 } }, "additionalProperties": false } }, "required": [ "file_path" ], "additionalProperties": false, "anyOf": [ { "required": [ "description" ] }, { "required": [ "title" ] }, { "required": [ "tags" ] }, { "required": [ "product" ] } ] } } } }, "responses": { "200": { "description": "Successfully queued Sirv metadata update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSirvMetadataUpdateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/WorkspaceCapabilityRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "zapierApiKey": [] } ], "summary": "Queue Sirv file metadata update", "tags": [ "Zapier automation" ] } }, "/api/zapier/sirv/tags": { "post": { "description": "Queue a Sirv file tag add or remove operation for the connected workspace account.", "operationId": "zapierSirvTags", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_path": { "type": "string", "minLength": 1 }, "action": { "default": "add", "type": "string", "enum": [ "add", "remove" ] }, "tags": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "required": [ "file_path", "tags" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully queued Sirv tag update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSirvTagsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/WorkspaceCapabilityRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "zapierApiKey": [] } ], "summary": "Queue Sirv file tag update", "tags": [ "Zapier automation" ] } }, "/api/zapier/remove-bg": { "post": { "description": "Remove the background from an image for Zapier and automation workflows.", "operationId": "zapierRemoveBackground", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "model": { "default": "birefnet", "type": "string", "enum": [ "birefnet", "birefnet-v2", "bria" ] }, "operating_resolution": { "default": "1024x1024", "type": "string", "enum": [ "1024x1024", "2048x2048", "2304x2304" ] } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully removed background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove background from image", "tags": [ "Zapier automation" ] } }, "/api/zapier/replace-bg": { "post": { "description": "Replace the background of an image for Zapier and automation workflows.", "operationId": "zapierReplaceBackground", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "prompt": { "type": "string" }, "ref_image_url": { "type": "string", "format": "uri" }, "color": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }, "color_mode": { "default": "smart", "type": "string", "enum": [ "smart", "simple" ] }, "model": { "default": "bria", "type": "string", "enum": [ "bria", "flux-kontext", "nano-banana", "solid-color" ] } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully replaced background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace image background", "tags": [ "Zapier automation" ] } }, "/api/zapier/upscale": { "post": { "description": "Enhance image resolution for Zapier and automation workflows.", "operationId": "zapierUpscaleImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "scale": { "default": 2, "type": "number", "minimum": 1, "maximum": 10 }, "model": { "default": "esrgan", "type": "string", "enum": [ "esrgan", "clarity", "topaz", "seedvr" ] } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully upscaled image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Upscale image resolution", "tags": [ "Zapier automation" ] } }, "/api/zapier/generate": { "post": { "description": "Generate images from a text description for Zapier and automation workflows.", "operationId": "zapierGenerateImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1 }, "model": { "default": "nano-banana-2", "type": "string", "enum": [ "flux2", "zimage", "gemini", "gemini-or", "seedream", "seedream-or", "gpt-image-2", "nano-banana-2", "nano-banana-2-lite" ] }, "aspect_ratio": { "default": "landscape_4_3", "type": "string", "enum": [ "square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9", "1:1", "16:9", "9:16", "4:3", "3:4", "21:9" ] }, "num_images": { "default": 1, "type": "integer", "minimum": 1, "maximum": 4 } }, "required": [ "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated images", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate image from text", "tags": [ "Zapier automation" ] } }, "/api/zapier/image-to-image": { "post": { "description": "Transform an image based on a text prompt for Zapier and automation workflows.", "operationId": "zapierImageToImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "prompt": { "type": "string" }, "model": { "default": "nano-banana-2-edit", "type": "string", "enum": [ "nano-banana-2-edit", "nano-banana-lite-edit", "reve-fast-edit", "zimage-i2i", "flux2-edit", "qwen-integrate-product", "qwen-multiple-angles", "qwen-remove-lighting", "seedream-edit", "gpt-image-2-edit" ] }, "strength": { "default": 0.85, "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully transformed image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Transform image with text prompt", "tags": [ "Zapier automation" ] } }, "/api/zapier/image-translation": { "post": { "description": "Translate visible text in an image while preserving the surrounding image style for Zapier and automation workflows.", "operationId": "zapierTranslateImageText", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "target_language": { "type": "string", "minLength": 1 }, "source_language": { "type": "string" }, "model": { "default": "gemini", "type": "string", "enum": [ "gemini", "gpt-image-2-edit", "seedream-edit", "nano-banana-lite-edit" ] } }, "required": [ "image_url", "target_language" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully translated image text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierImageTranslationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Translate text in image", "tags": [ "Zapier automation" ] } }, "/api/zapier/image-review": { "post": { "description": "Run product-image quality checks for Zapier and automation workflows, including dimensions, white background, watermark, centering, and unwanted shadow checks. The endpoint is charged as one image-review operation per request.", "operationId": "zapierReviewImageQuality", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "check_background": { "default": true, "type": "boolean" }, "check_watermark": { "default": true, "type": "boolean" }, "check_centered": { "default": false, "type": "boolean" }, "check_shadows": { "default": false, "type": "boolean" }, "min_width": { "type": "number" }, "min_height": { "type": "number" } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully reviewed image quality", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierImageReviewResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Review image quality", "tags": [ "Zapier automation" ] } }, "/api/zapier/product-description": { "post": { "description": "Generate product copy for Zapier and automation workflows from product details, an optional product image, and writing controls.", "operationId": "zapierGenerateProductDescription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S" }, "image_url": { "type": "string", "format": "uri" }, "brand": { "type": "string" }, "category": { "type": "string" }, "features": { "type": "string" }, "language": { "default": "en", "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt", "nl", "pl", "uk", "ja", "zh", "ko" ] }, "length": { "default": "medium", "type": "string", "enum": [ "short", "medium", "long" ] }, "price": { "type": "string" }, "specs": { "type": "string" }, "style": { "default": "professional", "type": "string", "enum": [ "professional", "casual", "luxury", "technical" ] }, "target_audience": { "type": "string" } }, "additionalProperties": false, "anyOf": [ { "required": [ "name" ] }, { "required": [ "image_url" ] } ] } } } }, "responses": { "200": { "description": "Successfully generated product description", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierProductDescriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate product description", "tags": [ "Zapier automation" ] } }, "/api/zapier/alt-text": { "post": { "description": "Generate descriptive alt text for Zapier and automation workflows.", "operationId": "zapierGenerateAltText", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "detail_level": { "default": "detailed-caption", "type": "string", "enum": [ "caption", "detailed-caption", "more-detailed-caption" ] }, "model": { "default": "florence", "type": "string", "enum": [ "florence", "gemini-flash", "gemini-3-flash" ] } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated alt text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AltTextResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate alt text for image", "tags": [ "Zapier automation" ] } }, "/api/zapier/depth-map": { "post": { "description": "Generate a depth map from an image for Zapier and automation workflows.", "operationId": "zapierGenerateDepthMap", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated depth map", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate depth map", "tags": [ "Zapier automation" ] } }, "/api/zapier/object-removal": { "post": { "description": "Remove objects from an image for Zapier and automation workflows.", "operationId": "zapierRemoveObjects", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "mask_url": { "type": "string", "format": "uri" } }, "required": [ "image_url", "mask_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully removed objects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove objects from image", "tags": [ "Zapier automation" ] } }, "/api/zapier/product-lifestyle": { "post": { "description": "Place a product in a lifestyle scene for Zapier and automation workflows.", "operationId": "zapierCreateProductLifestyle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "scene_description": { "type": "string" }, "ref_image_url": { "type": "string", "format": "uri" }, "model": { "default": "bria", "type": "string", "enum": [ "bria", "gemini", "gpt-image-2", "seedream", "flux2", "nano-banana-lite" ] }, "placement_type": { "default": "manual_placement", "type": "string", "enum": [ "original", "automatic", "manual_placement", "manual_padding" ] }, "position": { "default": "bottom_center", "type": "string", "enum": [ "bottom_center", "bottom_left", "bottom_right", "upper_center", "upper_left", "upper_right", "center_vertical", "center_horizontal", "left_center", "right_center" ] } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully created lifestyle shots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create product lifestyle shot", "tags": [ "Zapier automation" ] } }, "/api/zapier/virtual-try-on": { "post": { "description": "Virtually try clothing on a person for Zapier and automation workflows.", "operationId": "zapierVirtualTryOn", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "person_image_url": { "type": "string", "format": "uri" }, "garment_image_url": { "type": "string", "format": "uri" }, "model": { "default": "fal", "type": "string", "const": "fal" } }, "required": [ "person_image_url", "garment_image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated try-on image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Virtual clothing try-on", "tags": [ "Zapier automation" ] } }, "/api/zapier/image-to-3d": { "post": { "description": "Generate a 3D model from an image for Zapier and automation workflows.", "operationId": "zapierImageTo3d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "image_urls": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "format": "uri" } }, "model": { "default": "meshy", "type": "string", "enum": [ "meshy", "meshy-multi", "seed3d", "trellis", "trellis2", "hunyuan3d" ] }, "topology": { "default": "triangle", "type": "string", "enum": [ "triangle", "quad" ] }, "enable_pbr": { "default": true, "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated 3D model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model3DResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Convert image to 3D model", "tags": [ "Zapier automation" ] } }, "/api/zapier/video-generation": { "post": { "description": "Generate a video from text or image input for Zapier and automation workflows.", "operationId": "zapierGenerateVideo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "prompt": { "type": "string", "minLength": 1 }, "model": { "default": "veo31", "type": "string", "enum": [ "veo31", "veo31ref", "ltx", "kling", "kling-v3", "kling-v3-pro", "seedance-2-fast" ] }, "duration": { "type": "string" }, "resolution": { "type": "string" }, "aspect_ratio": { "default": "auto", "type": "string", "enum": [ "auto", "21:9", "16:9", "4:3", "9:16", "3:4", "1:1" ] }, "generate_audio": { "default": true, "type": "boolean" } }, "required": [ "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate video from text or image", "tags": [ "Zapier automation" ] } }, "/api/assets": { "get": { "description": "List assets in the DAM library with filtering, sorting, and pagination.", "operationId": "listAssets", "parameters": [ { "name": "search", "in": "query", "description": "Filter assets by filename search.", "required": false, "schema": { "type": "string" } }, { "name": "favorite", "in": "query", "description": "Filter by favorite status.", "required": false, "schema": { "type": "boolean" } }, { "name": "tags", "in": "query", "description": "Comma-separated tag IDs to filter by.", "required": false, "schema": { "type": "string" } }, { "name": "folderId", "in": "query", "description": "Folder ID, or root for the root level.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "in": "query", "description": "Linked product ID to filter by.", "required": false, "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "description": "Sort field.", "required": false, "schema": { "type": "string", "enum": [ "created_at", "filename" ], "default": "created_at" } }, { "name": "sortOrder", "in": "query", "description": "Sort direction.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "description": "Maximum number of assets to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Successfully listed assets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "List assets", "tags": [ "Assets" ] } }, "/api/assets/search": { "get": { "description": "Full-text search across assets using ranked matching.", "operationId": "searchAssets", "parameters": [ { "name": "q", "in": "query", "description": "Full-text search query.", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "description": "Maximum number of search hits to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "mimeType", "in": "query", "description": "Filter by MIME type.", "required": false, "schema": { "type": "string" } }, { "name": "sourceTool", "in": "query", "description": "Filter by source tool.", "required": false, "schema": { "type": "string" } }, { "name": "isFavorite", "in": "query", "description": "Filter by favorite status.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully searched assets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSearchResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Search assets", "tags": [ "Assets" ] } }, "/api/assets/{id}": { "get": { "description": "Get a single asset by ID with its stored asset details.", "operationId": "getAsset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get asset", "tags": [ "Assets" ] }, "patch": { "description": "Update editable asset fields such as filename, alt text, and favorite state.", "operationId": "updateAsset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isFavorite": { "type": "boolean" }, "filename": { "type": "string", "maxLength": 200 }, "sirvPath": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "parentAssetId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "showInLibrary": { "type": "boolean" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully updated asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update asset", "tags": [ "Assets" ] }, "delete": { "description": "Soft-delete an asset so it can be restored later.", "operationId": "deleteAsset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete asset", "tags": [ "Assets" ] } }, "/api/assets/{id}/metadata": { "get": { "description": "Get custom metadata for an asset, including template context when applied.", "operationId": "getAssetMetadata", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved asset metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMetadataResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get asset metadata", "tags": [ "Assets" ] }, "patch": { "description": "Update custom metadata fields on an asset.", "operationId": "updateAssetMetadata", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "select" ] }, "label": { "type": "string" } }, "required": [ "value", "type" ], "additionalProperties": false } }, "templateId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "metadata" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully updated asset metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMetadataResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update asset metadata", "tags": [ "Assets" ] } }, "/api/assets/{id}/alt-text": { "post": { "description": "AI-generate alt text for an asset and save it.", "operationId": "generateAssetAltText", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "detailLevel": { "default": "caption", "type": "string", "enum": [ "caption", "detailed-caption", "more-detailed-caption" ] }, "model": { "type": "string", "enum": [ "florence", "gemini-flash", "gemini-3-flash", "gpt-4o-mini" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated asset alt text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetAltTextResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate asset alt text", "tags": [ "Assets" ] } }, "/api/assets/bulk": { "post": { "description": "Perform a bulk operation on multiple assets.", "operationId": "bulkAssetOperation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assetIds": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "operation": { "type": "string", "enum": [ "favorite", "unfavorite", "delete", "addTags", "removeTags", "restore", "hardDelete", "moveToFolder", "copyToFolder" ] }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "folderId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "assetIds", "operation" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully applied bulk asset operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssetOperationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Bulk asset operation", "tags": [ "Assets" ] } }, "/api/assets/import-url": { "post": { "description": "Import an asset from an external URL into the DAM library.", "operationId": "importAssetUrl", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 5000, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 1024 }, "folderId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "customMetadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "select" ] }, "label": { "type": "string" } }, "required": [ "value", "type" ], "additionalProperties": false } }, "metadataTemplateId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "url", "filename" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully imported asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Import asset from URL", "tags": [ "Assets" ] } }, "/api/products": { "get": { "description": "List products in the PIM with filtering, sorting, readiness, and pagination.", "operationId": "listProducts", "parameters": [ { "name": "search", "in": "query", "description": "Search by product name or SKU.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "nameSearch", "in": "query", "description": "Search by product name.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "skuSearch", "in": "query", "description": "Search by product SKU.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "status", "in": "query", "description": "Filter by product status.", "required": false, "schema": { "type": "string", "enum": [ "active", "draft", "archived" ] } }, { "name": "externalSource", "in": "query", "description": "Filter by source system.", "required": false, "schema": { "type": "string", "enum": [ "shopify", "woocommerce", "manual", "csv", "sap" ] } }, { "name": "brand", "in": "query", "description": "Filter by brand.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "productType", "in": "query", "description": "Filter by product type.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "categoryId", "in": "query", "description": "Filter by category ID.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tags", "in": "query", "description": "Comma-separated product tags.", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "name": "vendorUserId", "in": "query", "description": "Filter to products assigned to a vendor user.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "hasAssets", "in": "query", "description": "Filter by whether products have linked assets.", "required": false, "schema": { "type": "string", "enum": [ "all", "with_assets", "without_assets" ] } }, { "name": "slotsFilter", "in": "query", "description": "Filter by product asset slot completeness.", "required": false, "schema": { "type": "string", "enum": [ "complete", "incomplete" ] } }, { "name": "channelId", "in": "query", "description": "Channel ID for readiness context.", "required": false, "schema": { "type": "string" } }, { "name": "channelPresetId", "in": "query", "description": "Channel preset ID for readiness context.", "required": false, "schema": { "type": "string" } }, { "name": "market", "in": "query", "description": "Market code for readiness context.", "required": false, "schema": { "type": "string" } }, { "name": "profileId", "in": "query", "description": "Readiness profile ID.", "required": false, "schema": { "type": "string" } }, { "name": "sourceInstanceId", "in": "query", "description": "Source instance ID for readiness context.", "required": false, "schema": { "type": "string" } }, { "name": "readinessGap", "in": "query", "description": "Readiness gap code to filter by.", "required": false, "schema": { "type": "string" } }, { "name": "readinessScoreLabel", "in": "query", "description": "Readiness score label to filter by.", "required": false, "schema": { "type": "string" } }, { "name": "readinessSmartView", "in": "query", "description": "Readiness smart view to filter by.", "required": false, "schema": { "type": "string" } }, { "name": "channelTargeting", "in": "query", "description": "Filter products by channel targeting decision.", "required": false, "schema": { "type": "string", "enum": [ "targeted", "excluded", "not_targeted", "all" ] } }, { "name": "advancedFilters", "in": "query", "description": "JSON-encoded advanced product filters.", "required": false, "schema": { "type": "string", "maxLength": 5000 } }, { "name": "limit", "in": "query", "description": "Maximum number of products to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor.", "required": false, "schema": { "type": "string", "maxLength": 2000 } }, { "name": "countMode", "in": "query", "description": "How the total count should be calculated.", "required": false, "schema": { "type": "string", "enum": [ "exact", "page-bound" ] } }, { "name": "sortBy", "in": "query", "description": "Sort field.", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "name", "sku", "updatedAt" ], "default": "createdAt" } }, { "name": "sortOrder", "in": "query", "description": "Sort direction.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "sort", "in": "query", "description": "Multi-sort rule string.", "required": false, "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "Successfully listed products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "List products", "tags": [ "Products" ] }, "post": { "description": "Create a product in the PIM catalog.", "operationId": "createProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 5000 }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "externalId": { "type": "string", "maxLength": 255 }, "externalSource": { "type": "string", "enum": [ "shopify", "woocommerce", "manual", "csv", "sap" ] }, "externalUrl": { "type": "string", "maxLength": 2000, "format": "uri" }, "productType": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "productCategory": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "categoryIds": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "sku", "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully created product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create product", "tags": [ "Products" ] } }, "/api/products/{id}": { "get": { "description": "Get a single product by ID, including readiness context when requested.", "operationId": "getProduct", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product identifier.", "schema": { "type": "string" } }, { "name": "channelId", "in": "query", "description": "Channel ID for readiness context.", "required": false, "schema": { "type": "string" } }, { "name": "channelPresetId", "in": "query", "description": "Channel preset ID for readiness context.", "required": false, "schema": { "type": "string" } }, { "name": "market", "in": "query", "description": "Market code for readiness context.", "required": false, "schema": { "type": "string" } }, { "name": "profileId", "in": "query", "description": "Readiness profile ID.", "required": false, "schema": { "type": "string" } }, { "name": "sourceInstanceId", "in": "query", "description": "Source instance ID for readiness context.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get product", "tags": [ "Products" ] }, "patch": { "description": "Update editable product fields in the PIM catalog.", "operationId": "updateProduct", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "brand": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "productCategory": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "productType": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "categoryIds": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "metafields": { "type": "array", "items": { "type": "object", "properties": { "namespace": { "type": "string", "maxLength": 255 }, "key": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "maxLength": 5000 } }, "required": [ "namespace", "key", "type", "value" ], "additionalProperties": false } }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "external_source": { "anyOf": [ { "type": "string", "enum": [ "shopify", "woocommerce", "manual", "csv", "sap" ] }, { "type": "null" } ] }, "external_url": { "anyOf": [ { "type": "string", "maxLength": 2000, "format": "uri" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully updated product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update product", "tags": [ "Products" ] }, "delete": { "description": "Delete a product from the PIM catalog.", "operationId": "deleteProduct", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete product", "tags": [ "Products" ] } }, "/api/products/search": { "get": { "description": "Search products by name or SKU with optional fuzzy matching.", "operationId": "searchProducts", "parameters": [ { "name": "q", "in": "query", "description": "Search query.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Maximum number of search results to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "mode", "in": "query", "description": "Search matching mode.", "required": false, "schema": { "type": "string", "enum": [ "fuzzy", "contains" ] } }, { "name": "includeTotal", "in": "query", "description": "Whether to include a total result count.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Successfully searched products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Search products", "tags": [ "Products" ] } }, "/api/products/with-assets": { "get": { "description": "List products with their linked asset details and asset counts.", "operationId": "listProductsWithAssets", "parameters": [ { "name": "search", "in": "query", "description": "Search by product name or SKU.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Maximum number of products to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "sortBy", "in": "query", "description": "Sort field.", "required": false, "schema": { "type": "string", "enum": [ "name", "createdAt", "assetCount" ], "default": "name" } }, { "name": "sortOrder", "in": "query", "description": "Sort direction.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "tagIds", "in": "query", "description": "Comma-separated asset tag IDs.", "required": false, "schema": { "type": "string", "maxLength": 2000 } }, { "name": "hideEmpty", "in": "query", "description": "Whether to hide products with no linked assets.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" } } ], "responses": { "200": { "description": "Successfully listed products with assets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductsWithAssetsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "List products with assets", "tags": [ "Products" ] } }, "/api/products/{id}/assets": { "post": { "description": "Link one or more assets to a product with optional merchandising role metadata.", "operationId": "linkAssetsToProduct", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "main", "gallery", "lifestyle", "detail", "swatch" ] }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "productVariantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "variantExternalId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "variantSku": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "slotKey": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "replaceAtSlot": { "type": "boolean" } }, "required": [ "assetId" ], "additionalProperties": false }, { "type": "object", "properties": { "assetIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "role": { "type": "string", "enum": [ "main", "gallery", "lifestyle", "detail", "swatch" ] }, "productVariantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "variantExternalId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "variantSku": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "slotKey": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "assetIds" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Successfully linked assets to product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAssetsToProductResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Link assets to product", "tags": [ "Products" ] } }, "/api/products/bulk": { "post": { "description": "Perform a bulk action such as delete, status update, field update, or asset linking.", "operationId": "bulkProductAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "deleteAll" } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "productIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "action", "productIds" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "updateStatus" }, "productIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] } }, "required": [ "action", "productIds", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "linkAssets" }, "productIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "assetIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "role": { "type": "string", "enum": [ "main", "gallery", "lifestyle", "detail", "swatch" ] } }, "required": [ "action", "productIds", "assetIds" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "updateFields" }, "productIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "fields": { "type": "object", "properties": { "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "tags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "tagMode": { "default": "merge", "type": "string", "enum": [ "merge", "replace" ] } }, "required": [ "action", "productIds", "fields", "tagMode" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Successfully applied bulk product action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkProductActionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Bulk product action", "tags": [ "Products" ] } }, "/api/fal/remove-background": { "post": { "description": "Remove the background from an image, leaving only the foreground subject with transparency. Ideal for product photos and portraits.", "operationId": "removeBackground", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "provider": { "type": "string", "enum": [ "birefnet", "bria" ] }, "model": { "type": "string" }, "version": { "type": "string", "enum": [ "v1", "v2" ] }, "v2_model": { "type": "string" }, "operating_resolution": { "type": "string", "enum": [ "1024x1024", "2048x2048", "2304x2304" ] }, "image_width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image_height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source_asset_id": { "type": "string" } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully removed background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove background from image", "tags": [ "AI image tools" ] } }, "/api/fal/upscale": { "post": { "description": "Upscale an image to a higher resolution using AI-powered super-resolution.", "operationId": "upscaleImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "scale": { "default": 2, "type": "number", "minimum": 1, "maximum": 10 }, "model": { "default": "esrgan", "type": "string", "enum": [ "esrgan", "clarity", "topaz", "seedvr" ] }, "prompt": { "type": "string" }, "creativity": { "type": "number", "minimum": 0, "maximum": 1 }, "resemblance": { "type": "number", "minimum": 0, "maximum": 1 }, "topaz_model": { "type": "string", "enum": [ "standard", "highFidelity", "recovery", "lowRes", "cgi", "textRefine", "redefine" ] }, "face_enhancement": { "type": "boolean" }, "face_enhancement_strength": { "type": "number", "minimum": 0, "maximum": 1 }, "face_enhancement_creativity": { "type": "number", "minimum": 0, "maximum": 1 }, "upscale_mode": { "type": "string", "enum": [ "target", "factor" ] }, "target_resolution": { "type": "string", "enum": [ "720p", "1080p", "1440p", "2160p" ] }, "noise_scale": { "type": "number", "minimum": 0, "maximum": 1 }, "seed": { "type": "number" }, "image_width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image_height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "asset_id": { "type": "string" } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully upscaled image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Upscale image resolution", "tags": [ "AI image tools" ] } }, "/api/fal/generate": { "post": { "description": "Generate images from a text description using Sirv AI Studio image models.", "operationId": "generateImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "model": { "default": "nano-banana-2", "type": "string", "enum": [ "flux2", "zimage", "gemini", "gemini-or", "seedream", "seedream-or", "gpt-image-2", "nano-banana-2", "nano-banana-2-lite" ] }, "aspect_ratio": { "default": "landscape_4_3", "type": "string" }, "num_images": { "default": 1, "type": "integer", "minimum": 1, "maximum": 4 }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ] }, "image_size": { "type": "string", "enum": [ "1024x1024", "1536x1024", "1024x1536" ] }, "quality": { "type": "string", "enum": [ "low", "medium", "high" ] }, "background": { "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "seed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated images", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate image from text", "tags": [ "AI image tools" ] } }, "/api/fal/image-to-image": { "post": { "description": "Transform an existing image based on a text prompt while preserving useful source-image context.", "operationId": "imageToImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "prompt": { "type": "string" }, "strength": { "default": 0.85, "type": "number", "minimum": 0, "maximum": 1 }, "model": { "default": "nano-banana-2-edit", "type": "string", "enum": [ "flux2-edit", "nano-banana-2-edit", "nano-banana-lite-edit", "qwen-integrate-product", "qwen-multiple-angles", "qwen-remove-lighting", "seedream-edit", "reve-fast-edit", "gpt-image-2-edit", "zimage-i2i" ] }, "horizontal_angle": { "type": "number", "minimum": 0, "maximum": 360 }, "vertical_angle": { "type": "number", "minimum": -30, "maximum": 90 }, "zoom": { "type": "number", "minimum": 0, "maximum": 10 }, "lora_scale": { "type": "number", "minimum": 0, "maximum": 1 }, "ref_image_url": { "type": "string", "format": "uri" }, "image_size": { "type": "string", "enum": [ "auto", "1024x1024", "1536x1024", "1024x1536" ] }, "quality": { "type": "string", "enum": [ "low", "medium", "high" ] }, "background": { "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "input_fidelity": { "type": "string", "enum": [ "low", "high" ] } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully transformed image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Transform image with text prompt", "tags": [ "AI image tools" ] } }, "/api/fal/image-translation": { "post": { "description": "Translate visible text in an image while preserving the original layout, typography, and image style.", "operationId": "translateImageText", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "source_language": { "type": "string" }, "target_language": { "type": "string", "minLength": 1 }, "model": { "default": "gemini", "type": "string", "enum": [ "gemini", "gpt-image-2-edit", "seedream-edit", "nano-banana-lite-edit" ] } }, "required": [ "image_url", "target_language" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully translated image text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Translate text in image", "tags": [ "AI image tools" ] } }, "/api/fal/background-replace": { "post": { "description": "Replace the background of an image while keeping the foreground subject intact.", "operationId": "replaceBackground", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "prompt": { "type": "string" }, "ref_image_url": { "type": "string", "format": "uri" }, "color": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }, "color_mode": { "default": "smart", "type": "string", "enum": [ "smart", "simple" ] }, "model": { "default": "bria", "type": "string", "enum": [ "bria", "flux-kontext", "nano-banana", "solid-color" ] }, "image_width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image_height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully replaced background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace image background", "tags": [ "AI image tools" ] } }, "/api/fal/object-removal": { "post": { "description": "Remove unwanted objects or fill a masked area with a prompt using AI inpainting.", "operationId": "removeObjects", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_url", "mask_url" ], "additionalProperties": false, "properties": { "image_url": { "type": "string", "format": "uri", "description": "HTTPS URL of the source image." }, "mask_url": { "type": "string", "format": "uri", "description": "HTTPS URL of the mask image." }, "operation": { "type": "string", "enum": [ "object-removal", "generative-fill" ], "default": "object-removal", "description": "Use generative-fill, or set mode to fill, to fill the masked area with a prompt." }, "mode": { "type": "string", "enum": [ "remove", "fill" ], "default": "remove" }, "model": { "type": "string", "enum": [ "qwen-inpaint", "bria-genfill", "gpt-image-2-edit" ], "default": "qwen-inpaint", "description": "Remove mode uses qwen-inpaint. Fill mode defaults to bria-genfill and also accepts gpt-image-2-edit." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Required when operation is generative-fill or mode is fill. Describe what should appear inside the masked area." }, "image_width": { "type": "integer", "minimum": 1 }, "image_height": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Successfully edited masked area", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove or fill masked image areas", "tags": [ "AI image tools" ] } }, "/api/fal/alt-text": { "post": { "description": "Generate descriptive alt text for an image using AI vision models.", "operationId": "generateAltText", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "detail_level": { "default": "detailed-caption", "type": "string", "enum": [ "caption", "detailed-caption", "more-detailed-caption" ] }, "model": { "default": "florence", "type": "string" } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated alt text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AltTextResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate alt text for image", "tags": [ "AI image tools" ] } }, "/api/fal/product-description": { "post": { "description": "Generate product copy from product details, an optional product image, writing controls, and workspace brand context.", "operationId": "generateProductDescription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S" }, "brand": { "type": "string" }, "category": { "type": "string" }, "features": { "type": "string" }, "language": { "default": "en", "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt", "nl", "pl", "uk", "ja", "zh", "ko" ] }, "length": { "default": "medium", "type": "string", "enum": [ "short", "medium", "long" ] }, "price": { "type": "string" }, "specs": { "type": "string" }, "style": { "default": "professional", "type": "string", "enum": [ "professional", "casual", "luxury", "technical" ] }, "targetAudience": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false, "anyOf": [ { "required": [ "name" ] }, { "required": [ "imageUrl" ] } ] } } } }, "responses": { "200": { "description": "Successfully generated product description", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDescriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate product description", "tags": [ "AI text tools" ] } }, "/api/fal/document-summary": { "post": { "description": "Fetch a PDF, DOCX, or text document from a safe URL and generate a summary with optional length, format, language, and focus controls.", "operationId": "summarizeDocument", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_url" ], "additionalProperties": false, "properties": { "document_url": { "type": "string", "format": "uri" }, "focus": { "type": "string", "maxLength": 200 }, "format": { "default": "paragraph", "type": "string", "enum": [ "paragraph", "bullets", "sections" ] }, "language": { "default": "en", "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt", "nl", "pl", "uk", "ja", "zh", "ko" ] }, "length": { "default": "standard", "type": "string", "enum": [ "brief", "standard", "detailed" ] } } } } } }, "responses": { "200": { "description": "Successfully summarized document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSummaryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ], "summary": "Summarize document", "tags": [ "AI text tools" ] } }, "/api/fal/pdf-translation": { "post": { "description": "Fetch a PDF from a safe URL and return a translated PDF in translated-only or bilingual output mode.", "operationId": "translatePdf", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_url", "target_language" ], "additionalProperties": false, "properties": { "document_url": { "type": "string", "format": "uri" }, "mode": { "default": "translated", "type": "string", "enum": [ "translated", "bilingual" ] }, "source_language": { "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt", "nl", "pl", "uk", "ja", "zh", "ko", "ar", "hi", "tr", "vi", "th", "id", "cs", "ru", "sv", "da", "no", "fi", "el", "he", "hu", "ro", "sk", "bg", "hr", "sr", "sl", "lt", "lv", "et", "ms", "tl", "bn", "ta", "te", "mr", "gu", "kn", "ml", "pa", "ur", "fa", "sw", "af" ] }, "target_language": { "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt", "nl", "pl", "uk", "ja", "zh", "ko", "ar", "hi", "tr", "vi", "th", "id", "cs", "ru", "sv", "da", "no", "fi", "el", "he", "hu", "ro", "sk", "bg", "hr", "sr", "sl", "lt", "lv", "et", "ms", "tl", "bn", "ta", "te", "mr", "gu", "kn", "ml", "pa", "ur", "fa", "sw", "af" ] } } } } } }, "responses": { "200": { "description": "Successfully translated PDF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfTranslationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ], "summary": "Translate PDF", "tags": [ "AI text tools" ] } }, "/api/fal/expand-prompt": { "post": { "description": "Expand a short prompt into detailed instructions for supported Studio AI workflows, optionally using safe image context and workspace brand context.", "operationId": "expandPrompt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt", "taskType" ], "additionalProperties": false, "properties": { "imageUrl": { "type": "string", "format": "uri" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 1000 }, "taskType": { "type": "string", "enum": [ "brand-context", "video-generation", "image-generation", "image-editing", "background-replace", "product-lifestyle" ] } } } } } }, "responses": { "200": { "description": "Successfully expanded prompt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptExpansionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ], "summary": "Expand prompt", "tags": [ "AI text tools" ] } }, "/api/fal/ai-router": { "post": { "description": "Classify an image into one of the caller-provided branch names for workflow routing decisions.", "operationId": "classifyImageRoute", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_url", "prompt", "branches" ], "additionalProperties": false, "properties": { "image_url": { "type": "string", "format": "uri" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "branches": { "type": "array", "minItems": 2, "maxItems": 20, "items": { "type": "object", "required": [ "id", "name" ], "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 240 } } } }, "fallback_branch": { "type": "string", "description": "Optional fallback branch name. Must match one of the supplied branch names.", "minLength": 1, "maxLength": 80 }, "model": { "type": "string", "enum": [ "gemini-flash", "gemini-3-flash", "qwen-vl-8b" ], "default": "gemini-flash" } } } } } }, "responses": { "200": { "description": "Successfully classified image route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRouterResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ], "summary": "Classify image route", "tags": [ "AI image tools" ] } }, "/api/fal/image-review": { "post": { "description": "Run product-image quality rules against one or more image URLs and return per-image pass/fail results with summary counts.", "operationId": "reviewImageQuality", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_urls", "rules" ], "additionalProperties": false, "properties": { "image_urls": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" } }, "rules": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "required": [ "id", "type", "enabled", "minWidth", "minHeight" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "min_dimension" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "minWidth": { "type": "number" }, "minHeight": { "type": "number" }, "match": { "type": "string", "enum": [ "both", "either" ] } } }, { "type": "object", "required": [ "id", "type", "enabled", "maxWidth", "maxHeight" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "max_dimension" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "maxWidth": { "type": "number" }, "maxHeight": { "type": "number" } } }, { "type": "object", "required": [ "id", "type", "enabled", "allowed" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "aspect_ratio" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "allowed": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "id", "type", "enabled", "maxBytes" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "file_size" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "maxBytes": { "type": "number" } } }, { "type": "object", "required": [ "id", "type", "enabled", "allowed" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "file_format" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "allowed": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "id", "type", "enabled", "allowed" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "video_codec" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "allowed": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "id", "type", "enabled", "tolerance" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "background_white" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "tolerance": { "type": "number" } } }, { "type": "object", "required": [ "id", "type", "enabled", "minPercent" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "frame_fill" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "minPercent": { "type": "number" } } }, { "type": "object", "required": [ "id", "type", "enabled" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "no_watermark" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } } } }, { "type": "object", "required": [ "id", "type", "enabled", "tolerance" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "centered_subject" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "tolerance": { "type": "number" } } }, { "type": "object", "required": [ "id", "type", "enabled", "minMargin", "maxMargin" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "whitespace_margin" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "minMargin": { "type": "number" }, "maxMargin": { "type": "number" }, "horizontalMinMargin": { "type": "number" }, "horizontalMaxMargin": { "type": "number" }, "verticalMinMargin": { "type": "number" }, "verticalMaxMargin": { "type": "number" } } }, { "type": "object", "required": [ "id", "type", "enabled" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "no_overexposure" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } } } }, { "type": "object", "required": [ "id", "type", "enabled" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "no_shadows" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } } } }, { "type": "object", "required": [ "id", "type", "enabled", "rejectBelow", "enhanceBelow" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "blur_quality" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "rejectBelow": { "type": "number" }, "enhanceBelow": { "type": "number" } } }, { "type": "object", "required": [ "id", "type", "enabled", "minScore" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "low_detail_quality" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "minScore": { "type": "number" } } }, { "type": "object", "required": [ "id", "type", "enabled", "backgroundWhiteThreshold", "minContrastThreshold" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "const": "white_on_white" }, "enabled": { "type": "boolean" }, "mediaTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "backgroundWhiteThreshold": { "type": "number" }, "minContrastThreshold": { "type": "number" }, "autofixBackgroundColor": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" } } } ], "discriminator": { "propertyName": "type" } } }, "strict_mode": { "type": "boolean", "default": true }, "pass_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "ai_model": { "type": "string", "enum": [ "gemini", "qwen-vl-8b", "qwen-vl-235b", "gemini-flash", "gemini-3-flash" ], "default": "qwen-vl-8b" } } } } } }, "responses": { "200": { "description": "Successfully reviewed image quality", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageReviewResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ], "summary": "Review image quality", "tags": [ "AI image tools" ] } }, "/api/fal/depth-map": { "post": { "description": "Generate a depth map from an image showing relative distances. Lighter areas are closer; darker areas are farther.", "operationId": "generateDepthMap", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "image_width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image_height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "asset_id": { "type": "string" } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated depth map", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate depth map", "tags": [ "AI image tools" ] } }, "/api/fal/product-lifestyle": { "post": { "description": "Place a product in a realistic lifestyle scene for marketing and commerce content.", "operationId": "createProductLifestyle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "scene_description": { "type": "string" }, "ref_image_url": { "type": "string", "format": "uri" }, "model": { "default": "bria", "type": "string", "enum": [ "bria", "gemini", "gpt-image-2", "seedream", "flux2", "nano-banana-lite" ] }, "placement_type": { "default": "manual_placement", "type": "string", "enum": [ "original", "automatic", "manual_placement", "manual_padding" ] }, "position": { "default": "bottom_center", "type": "string", "enum": [ "bottom_center", "bottom_left", "bottom_right", "upper_center", "upper_left", "upper_right", "center_vertical", "center_horizontal", "left_center", "right_center" ] }, "shot_size": { "default": [ 1000, 1000 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ] }, "num_results": { "default": 1, "type": "number", "minimum": 1, "maximum": 4 } }, "required": [ "image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully created lifestyle shots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create product lifestyle shot", "tags": [ "AI image tools" ] } }, "/api/fal/virtual-try-on": { "post": { "description": "Virtually try clothing on a person using AI.", "operationId": "virtualTryOn", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "person_image_url": { "type": "string", "format": "uri" }, "garment_image_url": { "type": "string", "format": "uri" }, "model": { "default": "fal", "type": "string", "enum": [ "fal", "gemini", "gpt", "flux", "fashn" ] } }, "required": [ "person_image_url", "garment_image_url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated try-on image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Virtual clothing try-on", "tags": [ "AI image tools" ] } }, "/api/fal/image-to-3d": { "post": { "description": "Convert a 2D image into a 3D model and return the generated model assets.", "operationId": "imageTo3d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "image_urls": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "format": "uri" } }, "model": { "default": "meshy", "type": "string", "enum": [ "meshy", "meshy-multi", "seed3d", "trellis", "trellis2", "hunyuan3d" ] }, "topology": { "type": "string", "enum": [ "triangle", "quad" ] }, "target_polycount": { "type": "number", "minimum": 100, "maximum": 300000 }, "enable_pbr": { "type": "boolean" }, "texture_size": { "type": "number" }, "generate_type": { "type": "string", "enum": [ "Normal", "LowPoly", "Geometry" ] }, "face_count": { "type": "number", "minimum": 40000, "maximum": 1500000 }, "resolution": { "type": "string", "enum": [ "512", "1024", "1536" ] }, "ss_sampling_steps": { "type": "number", "minimum": 1, "maximum": 50 }, "ss_guidance_strength": { "type": "number", "minimum": 0, "maximum": 10 }, "remesh": { "type": "boolean" }, "decimation_target": { "type": "number", "minimum": 100000, "maximum": 2000000 }, "seed": { "type": "number" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated 3D model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model3DResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Convert image to 3D model", "tags": [ "AI image tools" ] } }, "/api/fal/glb-optimize": { "post": { "description": "Optimize a binary .glb model up to 100 MB with mesh cleanup, Draco compression, optional simplification, and optional texture compression.", "operationId": "optimizeGlb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "glb_url" ], "additionalProperties": false, "properties": { "glb_url": { "type": "string", "format": "uri", "description": "HTTPS URL of a binary .glb file up to 100 MB." }, "simplify_ratio": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "simplify_error": { "default": 0.001, "type": "number", "minimum": 0, "maximum": 1 }, "dedup": { "default": true, "type": "boolean" }, "prune": { "default": true, "type": "boolean" }, "draco": { "default": true, "type": "boolean" }, "instance": { "default": true, "type": "boolean" }, "flatten": { "default": true, "type": "boolean" }, "join": { "default": true, "type": "boolean" }, "weld": { "default": true, "type": "boolean" }, "quantize": { "default": true, "type": "boolean" }, "texture_format": { "default": null, "type": [ "string", "null" ], "enum": [ "jpeg", "png", "webp", "avif", null ] }, "texture_size": { "default": null, "oneOf": [ { "const": 256 }, { "const": 512 }, { "const": 1024 }, { "const": 2048 }, { "const": 4096 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Successfully optimized GLB model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlbOptimizeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Optimize GLB model", "tags": [ "AI 3D tools" ], "x-sirv-credits": { "required": true, "cost": 2 } } }, "/api/fal/video-generation": { "post": { "description": "Generate a video from a text prompt or starting image using AI.", "operationId": "generateVideo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "prompt": { "type": "string", "minLength": 1 }, "model": { "default": "veo31", "type": "string", "enum": [ "veo31", "veo31ref", "ltx", "kling", "kling-v3", "kling-v3-pro", "seedance-2-fast" ] }, "duration": { "type": "string" }, "resolution": { "type": "string" }, "aspect_ratio": { "type": "string" }, "generate_audio": { "type": "boolean" } }, "required": [ "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successfully generated video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Generate video from text or image", "tags": [ "AI video tools" ] } }, "/api/fal/video-upscale": { "post": { "description": "Upscale supplier videos to listing quality.", "operationId": "upscaleVideo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url", "source_width", "source_height", "source_duration_seconds" ], "additionalProperties": false, "properties": { "video_url": { "type": "string", "format": "uri", "description": "HTTPS URL of the source video." }, "model": { "type": "string", "enum": [ "seedvr-video", "topaz-video" ], "default": "topaz-video" }, "scale": { "type": "integer", "enum": [ 2, 4 ], "default": 2 }, "target_resolution": { "type": "string", "enum": [ "auto", "720p", "1080p", "1440p", "2160p" ], "default": "auto" }, "source_width": { "type": "integer", "minimum": 16, "maximum": 7680 }, "source_height": { "type": "integer", "minimum": 16, "maximum": 7680 }, "source_duration_seconds": { "type": "number", "exclusiveMinimum": 0, "maximum": 300 }, "source_frame_rate": { "type": "number", "exclusiveMinimum": 0, "maximum": 120, "default": 30 }, "asset_id": { "type": "string" }, "source_asset_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Successfully upscaled video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MeteringUnavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Upscale video resolution", "tags": [ "AI video tools" ] } }, "/api/user/usage/stats": { "get": { "description": "Get current credit usage statistics for the authenticated account.", "operationId": "getUsageStats", "responses": { "200": { "description": "Successfully retrieved usage stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageStatsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get usage statistics", "tags": [ "Account" ] } } }, "components": { "headers": { "XRateLimitLimit": { "description": "Maximum requests allowed in the current rate-limit window.", "schema": { "type": "integer", "minimum": 0 } }, "XRateLimitRemaining": { "description": "Requests remaining in the current rate-limit window.", "schema": { "type": "integer", "minimum": 0 } }, "XRateLimitReset": { "description": "Unix timestamp, in seconds, when the rate-limit window resets.", "schema": { "type": "integer", "minimum": 0 } }, "RetryAfter": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "Request forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InsufficientCredits": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "MeteringUnavailable": { "description": "Programmatic request metering temporarily unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "WorkspaceCapabilityRequired": { "description": "Workspace capability required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable error message." }, "code": { "type": "string", "description": "Stable machine-readable error code when available." }, "details": { "description": "Optional structured context for validation or provider failures." }, "eventId": { "type": "string", "description": "Sentry event identifier for server-side failures when available." }, "retryAfterMs": { "type": "integer", "minimum": 0, "description": "Suggested retry delay in milliseconds when available." }, "retryable": { "type": "boolean", "description": "Whether the caller can retry the failed request." } } }, "UrlResource": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public URL for the generated or processed resource." } } }, "ImageResponse": { "type": "object", "properties": { "image": { "$ref": "#/components/schemas/UrlResource" } } }, "MultiImageResponse": { "type": "object", "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/UrlResource" } } } }, "VideoResponse": { "type": "object", "properties": { "video": { "$ref": "#/components/schemas/UrlResource" } } }, "Model3DResponse": { "type": "object", "properties": { "fbx": { "$ref": "#/components/schemas/UrlResource" }, "glb": { "$ref": "#/components/schemas/UrlResource" }, "obj": { "$ref": "#/components/schemas/UrlResource" }, "thumbnail": { "$ref": "#/components/schemas/UrlResource" }, "usdz": { "$ref": "#/components/schemas/UrlResource" } } }, "AltTextResponse": { "type": "object", "properties": { "caption": { "type": "string", "description": "Generated alt text or caption." } } }, "AiRouterResponse": { "type": "object", "required": [ "selectedBranch", "model", "modelId" ], "additionalProperties": false, "properties": { "selectedBranch": { "type": "string", "description": "Selected branch name from the supplied branch list." }, "reasoning": { "type": "string", "description": "Optional model reasoning for the selected branch." }, "model": { "type": "string", "enum": [ "gemini-flash", "gemini-3-flash", "qwen-vl-8b" ] }, "modelId": { "type": "string", "description": "Provider model identifier used for classification." } } }, "ProductDescriptionResponse": { "type": "object", "required": [ "description", "style", "length", "language", "brandContext" ], "properties": { "brandContext": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "Workspace brand context metadata applied to the prompt, or null." }, "description": { "type": "string", "description": "Generated product description text." }, "language": { "type": "string", "description": "Language used for the generated description." }, "length": { "type": "string", "enum": [ "short", "medium", "long" ], "description": "Requested product description length." }, "style": { "type": "string", "enum": [ "professional", "casual", "luxury", "technical" ], "description": "Requested writing style." } } }, "DocumentSummaryResponse": { "type": "object", "required": [ "summary", "metadata" ], "additionalProperties": false, "properties": { "summary": { "type": "string", "description": "Generated document summary." }, "keyPoints": { "type": "array", "description": "Optional extracted key points for bullet or section summaries.", "items": { "type": "string" } }, "metadata": { "type": "object", "required": [ "documentType", "originalLength", "summaryLength" ], "additionalProperties": false, "properties": { "documentType": { "type": "string", "description": "Detected document type label." }, "originalLength": { "type": "number", "description": "Source text character count before summary generation." }, "summaryLength": { "type": "number", "description": "Generated summary character count." }, "truncated": { "type": "boolean", "description": "Whether source text was truncated before summary generation." } } } } }, "PdfTranslationResponse": { "type": "object", "required": [ "document", "pageCount", "mode" ], "additionalProperties": false, "properties": { "document": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "description": "Temporary URL for the translated PDF." } } }, "pageCount": { "type": "number", "description": "Number of pages processed in the source PDF." }, "mode": { "type": "string", "enum": [ "translated", "bilingual" ], "description": "Translation layout mode used for the output PDF." } } }, "GlbOptimizeResponse": { "type": "object", "required": [ "optimizedUrl", "originalSize", "optimizedSize", "reductionPercent", "vertexCount", "triangleCount" ], "additionalProperties": false, "properties": { "optimizedUrl": { "type": "string", "format": "uri", "description": "Temporary URL for the optimized GLB model." }, "originalSize": { "type": "number", "minimum": 0, "description": "Source GLB size in bytes." }, "optimizedSize": { "type": "number", "minimum": 0, "description": "Optimized GLB size in bytes." }, "reductionPercent": { "type": "number", "description": "Rounded percentage file-size reduction." }, "vertexCount": { "type": "object", "required": [ "before", "after" ], "additionalProperties": false, "properties": { "before": { "type": "number", "minimum": 0 }, "after": { "type": "number", "minimum": 0 } } }, "triangleCount": { "type": "object", "required": [ "before", "after" ], "additionalProperties": false, "properties": { "before": { "type": "number", "minimum": 0 }, "after": { "type": "number", "minimum": 0 } } } } }, "PromptExpansionResponse": { "type": "object", "required": [ "brandContext", "expandedPrompt", "model", "modelId" ], "additionalProperties": false, "properties": { "brandContext": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "Workspace brand context metadata applied to the prompt, or null." }, "expandedPrompt": { "type": "string", "description": "Expanded prompt text." }, "model": { "type": "string", "enum": [ "prompt-expansion" ], "description": "Studio model key charged for this request." }, "modelId": { "type": "string", "description": "Provider model identifier used for prompt expansion." } } }, "ImageReviewRuleResult": { "type": "object", "required": [ "ruleId", "ruleType", "passed", "message" ], "additionalProperties": false, "properties": { "ruleId": { "type": "string", "description": "Identifier of the rule that produced this result." }, "ruleType": { "type": "string", "description": "Image review rule type, such as min_dimension or no_watermark." }, "passed": { "type": "boolean", "description": "Whether this individual rule passed for the image." }, "message": { "type": "string", "description": "Human-readable rule outcome." }, "details": { "type": "object", "additionalProperties": true, "description": "Optional structured details from deterministic or AI-backed checks." } } }, "ImageReviewResult": { "type": "object", "required": [ "imageUrl", "passed", "ruleResults", "score" ], "additionalProperties": false, "properties": { "imageUrl": { "type": "string", "format": "uri", "description": "Reviewed source image URL." }, "passed": { "type": "boolean", "description": "Whether the image passed the requested rule set." }, "ruleResults": { "type": "array", "description": "Per-rule review outcomes for this image.", "items": { "$ref": "#/components/schemas/ImageReviewRuleResult" } }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized pass score for the image." }, "analysisMode": { "type": "string", "enum": [ "full", "metadata_only", "metadata_unavailable" ], "description": "How much deterministic analysis was available for the image." }, "analysisWarning": { "type": [ "string", "null" ], "description": "Warning explaining degraded analysis, when present." }, "rulesetFingerprint": { "type": [ "string", "null" ], "description": "Stable fingerprint of the evaluated rule set, when available." } } }, "ImageReviewResponse": { "type": "object", "required": [ "results", "passed", "failed", "summary" ], "additionalProperties": false, "properties": { "results": { "type": "array", "description": "Per-image review results.", "items": { "$ref": "#/components/schemas/ImageReviewResult" } }, "passed": { "type": "array", "description": "Image URLs that passed the requested rule set.", "items": { "type": "string", "format": "uri" } }, "failed": { "type": "array", "description": "Image URLs that failed the requested rule set.", "items": { "type": "string", "format": "uri" } }, "summary": { "type": "object", "required": [ "total", "passedCount", "failedCount", "passRate" ], "additionalProperties": false, "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of image URLs reviewed." }, "passedCount": { "type": "integer", "minimum": 0, "description": "Number of images that passed." }, "failedCount": { "type": "integer", "minimum": 0, "description": "Number of images that failed." }, "passRate": { "type": "number", "minimum": 0, "maximum": 1, "description": "Passed image count divided by total image count." } } } } }, "UsageStatsResponse": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "remaining": { "type": "integer", "description": "Credits remaining in the current period." }, "tier": { "type": "string", "description": "Subscription tier name." }, "total": { "type": "integer", "description": "Total credits for the current period." }, "used": { "type": "integer", "description": "Credits used in the current period." } } } } }, "ZapierAuthenticatedUserResponse": { "type": "object", "required": [ "id", "email", "credits", "tier" ], "properties": { "id": { "type": "string", "description": "Authenticated user identifier." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Authenticated user email address when available." }, "credits": { "type": "number", "description": "Credits currently available to the authenticated user." }, "tier": { "type": "string", "description": "Stored subscription tier for the authenticated user." } } }, "ZapierSirvSearchHit": { "type": "object", "additionalProperties": false, "properties": { "basename": { "type": "string", "description": "File basename returned by Sirv." }, "contentType": { "type": "string", "description": "File content type returned by Sirv." }, "ctime": { "type": "string", "description": "File creation timestamp returned by Sirv." }, "dirname": { "type": "string", "description": "Directory path returned by Sirv." }, "extension": { "type": "string", "description": "File extension returned by Sirv." }, "filename": { "type": "string", "description": "Full file path returned by Sirv." }, "height": { "type": "integer", "minimum": 0, "description": "Image height in pixels when Sirv returns it." }, "isDirectory": { "type": "boolean", "description": "Whether the result is a directory." }, "mtime": { "type": "string", "description": "File modification timestamp returned by Sirv." }, "size": { "type": "integer", "minimum": 0, "description": "File size in bytes when Sirv returns it." }, "width": { "type": "integer", "minimum": 0, "description": "Image width in pixels when Sirv returns it." } } }, "ZapierSirvSearchResponse": { "type": "object", "required": [ "id", "query", "hits", "total", "took" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "query": { "type": "string", "description": "Search query that was executed." }, "hits": { "type": "array", "description": "Stable public Sirv search hit fields returned by the Sirv API.", "items": { "$ref": "#/components/schemas/ZapierSirvSearchHit" } }, "total": { "type": "integer", "minimum": 0, "description": "Total matching files reported by Sirv." }, "took": { "type": "integer", "minimum": 0, "description": "Search execution time reported by Sirv, in milliseconds." } } }, "ZapierSirvFileInfo": { "type": "object", "required": [ "filename", "ctime", "mtime", "size", "contentType", "isDirectory" ], "additionalProperties": false, "properties": { "filename": { "type": "string", "description": "Full file path returned by Sirv." }, "ctime": { "type": "string", "description": "File creation timestamp returned by Sirv." }, "mtime": { "type": "string", "description": "File modification timestamp returned by Sirv." }, "size": { "type": "integer", "minimum": 0, "description": "File size in bytes." }, "contentType": { "type": "string", "description": "File content type." }, "isDirectory": { "type": "boolean", "description": "Whether the file info describes a directory." } } }, "ZapierSirvProductMetadata": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 256, "description": "Sirv product metadata ID." }, "name": { "type": "string", "maxLength": 256, "description": "Sirv product metadata name." }, "brand": { "type": "string", "maxLength": 256, "description": "Sirv product metadata brand." }, "category1": { "type": "string", "maxLength": 256, "description": "Primary Sirv product metadata category." }, "category2": { "type": "string", "maxLength": 256, "description": "Secondary Sirv product metadata category." } } }, "ZapierSirvMetadata": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 256, "description": "Sirv meta title." }, "description": { "type": "string", "maxLength": 1024, "description": "Sirv meta description, commonly used as image alt text." }, "tags": { "type": "array", "maxItems": 50, "description": "Sirv meta tags.", "items": { "type": "string", "maxLength": 32 } }, "product": { "$ref": "#/components/schemas/ZapierSirvProductMetadata" } } }, "ZapierSirvGetMetadataResponse": { "type": "object", "required": [ "id", "file_path", "metadata", "file_info" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "file_path": { "type": "string", "description": "Validated Sirv file path used for the metadata lookup." }, "metadata": { "$ref": "#/components/schemas/ZapierSirvMetadata" }, "file_info": { "oneOf": [ { "$ref": "#/components/schemas/ZapierSirvFileInfo" }, { "type": "null" } ], "description": "Stable Sirv file info fields, or null when the stat lookup is unavailable." } } }, "ZapierSirvMetadataUpdateResponse": { "type": "object", "required": [ "id", "file_path", "metadata", "queued" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "file_path": { "type": "string", "description": "Validated Sirv file path queued for metadata update." }, "metadata": { "$ref": "#/components/schemas/ZapierSirvMetadata" }, "queued": { "type": "boolean", "description": "Whether the metadata update has been queued for processing." } } }, "ZapierSirvTagsResponse": { "type": "object", "required": [ "id", "file_path", "action", "tags", "queued" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "file_path": { "type": "string", "description": "Validated Sirv file path queued for tag update." }, "action": { "type": "string", "enum": [ "add", "remove" ], "description": "Queued tag operation." }, "tags": { "type": "array", "maxItems": 50, "description": "Tag values queued for the operation.", "items": { "type": "string", "maxLength": 32 } }, "queued": { "type": "boolean", "description": "Whether the tag update has been queued for processing." } } }, "ZapierSirvFileOperationResponse": { "type": "object", "required": [ "id", "action", "file_path", "queued" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "action": { "type": "string", "enum": [ "rename", "copy", "delete" ], "description": "Queued Sirv file operation." }, "file_path": { "type": "string", "description": "Validated Sirv file path queued for the operation." }, "target_path": { "type": "string", "description": "Validated destination path for rename and copy operations." }, "queued": { "type": "boolean", "description": "Whether the file operation has been queued for processing." } } }, "ZapierSirvFolderItem": { "type": "object", "additionalProperties": false, "properties": { "filename": { "type": "string", "description": "Folder item filename returned by Sirv." }, "dirname": { "type": "string", "description": "Directory path for the folder item." }, "basename": { "type": "string", "description": "Folder item basename." }, "contentType": { "type": "string", "description": "Folder item content type returned by Sirv." }, "mtime": { "type": "string", "description": "File modification timestamp returned by Sirv." }, "ctime": { "type": "string", "description": "File creation timestamp returned by Sirv." }, "size": { "type": "integer", "minimum": 0, "description": "File size in bytes when Sirv returns it." }, "isDirectory": { "type": "boolean", "description": "Whether the folder item is a directory." } } }, "ZapierSirvFolderOperationResponse": { "type": "object", "required": [ "id", "action", "folder_path" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "action": { "type": "string", "enum": [ "create", "list" ], "description": "Sirv folder operation." }, "folder_path": { "type": "string", "description": "Validated Sirv folder path used for the operation." }, "queued": { "type": "boolean", "description": "Whether the folder creation has been queued for processing." }, "contents": { "type": "array", "description": "Stable public Sirv folder item fields.", "items": { "$ref": "#/components/schemas/ZapierSirvFolderItem" } }, "continuation": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sirv continuation cursor for the next page, when available." }, "total": { "type": "integer", "minimum": 0, "description": "Number of folder items returned in this response." } } }, "ZapierSirvUploadResponse": { "type": "object", "required": [ "id", "url" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "url": { "type": "string", "format": "uri", "description": "Public Sirv CDN URL for the uploaded file." }, "folder": { "type": "string", "description": "Validated destination folder when the upload used folder plus filename." }, "filename": { "type": "string", "description": "Validated filename when the upload used folder plus filename." }, "target_path": { "type": "string", "description": "Validated full Sirv target path when supplied." } } }, "ZapierImageTranslationResponse": { "type": "object", "required": [ "id", "image_url", "target_language", "credits_used" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "image_url": { "type": "string", "format": "uri", "description": "URL of the translated image." }, "target_language": { "type": "string", "description": "Target language used for the translated image text." }, "credits_used": { "type": "number", "minimum": 0, "description": "Credits charged for the translation." } } }, "ZapierImageReviewResult": { "type": "object", "required": [ "check", "passed", "message" ], "additionalProperties": false, "properties": { "check": { "type": "string", "description": "Stable check identifier, such as min_width or no_watermark." }, "passed": { "type": "boolean", "description": "Whether this individual review check passed." }, "message": { "type": "string", "description": "Human-readable review outcome for this check." }, "confidence": { "type": "number", "minimum": 0, "maximum": 100, "description": "AI confidence score for model-backed checks, when available." } } }, "ZapierImageReviewResponse": { "type": "object", "required": [ "id", "passed", "results", "summary", "credits_used" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "passed": { "type": "boolean", "description": "Whether every requested review check passed." }, "results": { "type": "array", "description": "Per-check image review results.", "items": { "$ref": "#/components/schemas/ZapierImageReviewResult" } }, "summary": { "type": "object", "required": [ "total_checks", "passed_checks", "failed_checks" ], "additionalProperties": false, "properties": { "total_checks": { "type": "integer", "minimum": 0, "description": "Number of review checks executed." }, "passed_checks": { "type": "integer", "minimum": 0, "description": "Number of review checks that passed." }, "failed_checks": { "type": "integer", "minimum": 0, "description": "Number of review checks that failed." } } }, "credits_used": { "type": "number", "minimum": 0, "description": "Credits charged for this one image-review request." } } }, "ZapierProductDescriptionResponse": { "type": "object", "required": [ "id", "description", "style", "length", "language", "credits_used" ], "properties": { "id": { "type": "string", "description": "Zapier-compatible result identifier." }, "description": { "type": "string", "description": "Generated product description text." }, "style": { "type": "string", "enum": [ "professional", "casual", "luxury", "technical" ], "description": "Requested writing style." }, "length": { "type": "string", "enum": [ "short", "medium", "long" ], "description": "Requested product description length." }, "language": { "type": "string", "description": "Language used for the generated description." }, "credits_used": { "type": "number", "minimum": 0, "description": "Credits charged for the generated product description." } } }, "Asset": { "type": "object", "required": [ "id", "url" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Asset identifier." }, "url": { "type": "string", "format": "uri", "description": "Public asset URL." }, "filename": { "type": "string", "description": "Display filename." }, "mimeType": { "type": "string", "description": "Asset MIME type." }, "isFavorite": { "type": "boolean", "description": "Whether the asset is marked as a favorite." } } }, "AssetListResponse": { "type": "object", "required": [ "assets", "total" ], "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "total": { "type": "integer", "minimum": 0, "description": "Total matching assets." } } }, "AssetSearchResponse": { "type": "object", "required": [ "hits", "query", "total" ], "properties": { "hits": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "query": { "type": "string", "description": "Search query that was executed." }, "total": { "type": "integer", "minimum": 0, "description": "Total matching search hits." } } }, "AssetMetadataResponse": { "type": "object", "required": [ "metadata" ], "additionalProperties": true, "properties": { "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata values keyed by field name." }, "templateId": { "type": [ "string", "null" ], "description": "Applied metadata template identifier, when present." } } }, "AssetAltTextResponse": { "type": "object", "required": [ "altText" ], "properties": { "altText": { "type": "string", "description": "Generated or stored alt text." } } }, "AssetDeleteResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Whether the asset was deleted." }, "success": { "type": "boolean", "description": "Whether the delete operation succeeded." } } }, "BulkAssetOperationResponse": { "type": "object", "required": [ "count" ], "additionalProperties": true, "properties": { "count": { "type": "integer", "minimum": 0, "description": "Number of assets affected." }, "success": { "type": "boolean", "description": "Whether the bulk operation succeeded." } } }, "Product": { "type": "object", "required": [ "id", "name", "sku", "status" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Product identifier." }, "sku": { "type": "string", "description": "Product SKU." }, "name": { "type": "string", "description": "Product name." }, "description": { "type": [ "string", "null" ], "description": "Product description." }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ], "description": "Product lifecycle status." }, "brand": { "type": [ "string", "null" ], "description": "Product brand." }, "productCategory": { "type": [ "string", "null" ], "description": "Product category." }, "productType": { "type": [ "string", "null" ], "description": "Product type." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Product tags." } } }, "ProductWithAssets": { "type": "object", "required": [ "id", "name", "sku", "status", "assets" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Product identifier." }, "sku": { "type": "string", "description": "Product SKU." }, "name": { "type": "string", "description": "Product name." }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ], "description": "Product lifecycle status." }, "assetCount": { "type": "integer", "minimum": 0, "description": "Number of linked assets." }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } }, "ProductListResponse": { "type": "object", "required": [ "products", "total" ], "additionalProperties": true, "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "total": { "type": "integer", "minimum": 0, "description": "Total matching products." }, "hasMore": { "type": "boolean", "description": "Whether more products are available after this page." }, "totalExact": { "type": "boolean", "description": "Whether the total count is exact." }, "nextCursor": { "type": "string", "description": "Cursor for the next page when cursor pagination is used." } } }, "ProductSearchResponse": { "type": "object", "required": [ "products" ], "additionalProperties": true, "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "total": { "type": "integer", "minimum": 0, "description": "Total matching products when requested." } } }, "ProductsWithAssetsResponse": { "type": "object", "required": [ "products", "total", "hasMore" ], "additionalProperties": true, "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithAssets" } }, "total": { "type": "integer", "minimum": 0, "description": "Total matching products." }, "hasMore": { "type": "boolean", "description": "Whether more products are available after this page." } } }, "ProductDeleteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the product was deleted." }, "deleted": { "type": "boolean", "description": "Whether the delete operation removed a product." } } }, "LinkAssetsToProductResponse": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean", "description": "Whether the link operation succeeded." }, "linked": { "type": "integer", "minimum": 0, "description": "Number of assets linked to the product." } } }, "BulkProductActionResponse": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer", "minimum": 0, "description": "Number of products affected." }, "success": { "type": "boolean", "description": "Whether the bulk operation succeeded." } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key or OAuth access token." }, "zapierApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_*", "description": "Zapier API key using the `Authorization: Bearer sk_live_...` header." } } }, "security": [ { "bearerAuth": [] } ] }