{
"openapi": "3.1.0",
"servers": [
{
"url": "https://api.developer.pixelcut.ai",
"description": "Pixelcut API server"
}
],
"info": {
"description": "The Pixelcut API specification, learn more about the API at at https://www.pixelcut.ai/docs",
"version": "0.0.2",
"title": "Pixelcut API",
"termsOfService": "https://pixelcut.notion.site/Pixelcut-API-Terms-of-Service-11b3b550490080d89a91e943d010efdf",
"contact": {
"name": "API Support",
"email": "api@pixelcut.ai"
}
},
"paths": {
"/v1/upscale": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Upscale",
"description": "Increases the resolution of an image by 2x or 4x. Images may be upscaled to a maximum resolution of 6000x6000px. Upscaled images are returned in JPEG format unless the input image contained alpha channels, in which case the output will be PNG format.
**Input Image Limits:**\n - Max size: 25MB\n - Min resolution: 64x64px\n - Max resolution: 6000x6000px\n",
"operationId": "upscale",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SameTypeAsRequestJSONResponse"
}
},
"image/*": {
"schema": {
"$ref": "#/components/schemas/SameTypeAsRequestBinaryResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"403": {
"$ref": "#/components/responses/Error403"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
],
"parameters": [
{
"in": "header",
"name": "Accept",
"required": false,
"schema": {
"type": "string"
},
"description": "Acceptable response media type(s). `application/json`, `image/*`. Default is `application/json`."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image_url",
"scale"
],
"properties": {
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"scale": {
"$ref": "#/components/schemas/ScaleParameter"
}
}
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"image": {
"$ref": "#/components/schemas/BinaryImageParameter"
},
"scale": {
"$ref": "#/components/schemas/ScaleParameter"
}
}
}
}
}
}
}
},
"/v1/outpaint": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Outpaint",
"description": "Expands an image by generating AI content beyond its original boundaries. Use this to extend images in any direction while maintaining visual coherence.
**Input Image Limits:**\n - Max size: 25MB\n - Min resolution: 128x128px\n - Max resolution: 6000x6000px\n - Supported formats: JPEG, PNG (PNG will be converted to JPEG for processing)\n
**Expansion Limits:**\n - Each direction (left, top, right, bottom) can be extended by 0-2000 pixels\n - At least one direction must have a non-zero value\n",
"operationId": "outpaint",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JpegImageJSONResponse"
}
},
"image/*": {
"schema": {
"$ref": "#/components/schemas/JpegBinaryResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"403": {
"$ref": "#/components/responses/Error403"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
],
"parameters": [
{
"in": "header",
"name": "Accept",
"required": false,
"schema": {
"type": "string"
},
"description": "Acceptable response media type(s). `application/json`, `image/*`. Default is `application/json`."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image_url"
],
"properties": {
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"left": {
"$ref": "#/components/schemas/OutpaintPixelParameter"
},
"top": {
"$ref": "#/components/schemas/OutpaintPixelParameter"
},
"right": {
"$ref": "#/components/schemas/OutpaintPixelParameter"
},
"bottom": {
"$ref": "#/components/schemas/OutpaintPixelParameter"
},
"creativity": {
"$ref": "#/components/schemas/OutpaintCreativityParameter"
},
"output_format": {
"$ref": "#/components/schemas/OutpaintOutputFormatParameter"
}
}
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"image": {
"$ref": "#/components/schemas/BinaryImageParameter"
},
"left": {
"$ref": "#/components/schemas/OutpaintPixelParameter"
},
"top": {
"$ref": "#/components/schemas/OutpaintPixelParameter"
},
"right": {
"$ref": "#/components/schemas/OutpaintPixelParameter"
},
"bottom": {
"$ref": "#/components/schemas/OutpaintPixelParameter"
},
"creativity": {
"$ref": "#/components/schemas/OutpaintCreativityParameter"
},
"output_format": {
"$ref": "#/components/schemas/OutpaintOutputFormatParameter"
}
}
}
}
}
}
}
},
"/v1/remove-background": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Remove Background",
"description": "Removes the background from an image and optionally adds AI-generated shadows, crops to the subject, and applies margins. When AI shadows are requested, an additional 3 credits will be consumed.
**Input Image Limits:**\n - Formats: JPEG, PNG, WebP, HEIC, AVIF\n - Max size: 25MB\n - Min resolution: 64x64px\n - Max resolution: 10000x10000px\n",
"operationId": "remove-background",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PngImageJSONResponse"
}
},
"image/*": {
"schema": {
"$ref": "#/components/schemas/PngBinaryResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"403": {
"$ref": "#/components/responses/Error403"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
],
"parameters": [
{
"in": "header",
"name": "Accept",
"required": false,
"schema": {
"type": "string"
},
"description": "Acceptable response media type(s). `application/json` or `image/*`. Default is `application/json`."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image_url"
],
"properties": {
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"format": {
"$ref": "#/components/schemas/ImageFormatParameter"
},
"shadow": {
"$ref": "#/components/schemas/ShadowParameter"
},
"crop": {
"$ref": "#/components/schemas/CropParameter"
},
"margin": {
"$ref": "#/components/schemas/MarginParameter"
},
"margin_left": {
"$ref": "#/components/schemas/DirectionalMarginParameter"
},
"margin_right": {
"$ref": "#/components/schemas/DirectionalMarginParameter"
},
"margin_top": {
"$ref": "#/components/schemas/DirectionalMarginParameter"
},
"margin_bottom": {
"$ref": "#/components/schemas/DirectionalMarginParameter"
}
}
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"image": {
"$ref": "#/components/schemas/BinaryImageParameter"
},
"format": {
"$ref": "#/components/schemas/ImageFormatParameter"
},
"shadow": {
"$ref": "#/components/schemas/ShadowParameter"
},
"crop": {
"$ref": "#/components/schemas/CropParameter"
},
"margin": {
"$ref": "#/components/schemas/MarginParameter"
},
"margin_left": {
"$ref": "#/components/schemas/DirectionalMarginParameter"
},
"margin_right": {
"$ref": "#/components/schemas/DirectionalMarginParameter"
},
"margin_top": {
"$ref": "#/components/schemas/DirectionalMarginParameter"
},
"margin_bottom": {
"$ref": "#/components/schemas/DirectionalMarginParameter"
}
}
}
}
}
}
}
},
"/v1/generate-background": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Generate Background",
"description": "Generates a new background for an image. Generated images are 1024x1024 by default.
**Input Image Limits:**\n - Max size: 25MB\n - Min resolution: 64x64px\n - Max resolution: 6000x6000px\n",
"operationId": "generate-background",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JpegImageJSONResponse"
}
},
"image/*": {
"schema": {
"$ref": "#/components/schemas/JpegBinaryResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"403": {
"$ref": "#/components/responses/Error403"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
],
"parameters": [
{
"in": "header",
"name": "Accept",
"required": false,
"schema": {
"type": "string"
},
"description": "Acceptable response media type(s). `application/json` or `image/*`. Default is `application/json`."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image_url": {
"$ref": "#/components/schemas/GenerateImageURLParameter"
},
"image_transform": {
"$ref": "#/components/schemas/ImageTransform"
},
"scene": {
"$ref": "#/components/schemas/GenerateImageScene"
},
"prompt": {
"$ref": "#/components/schemas/GenerateImagePrompt"
},
"negative_prompt": {
"$ref": "#/components/schemas/GenerateImageNegativePrompt"
}
}
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"image": {
"$ref": "#/components/schemas/BinaryImageParameter"
},
"image_transform": {
"$ref": "#/components/schemas/ImageTransform"
},
"scene": {
"$ref": "#/components/schemas/GenerateImageScene"
},
"prompt": {
"$ref": "#/components/schemas/GenerateImagePrompt"
},
"negative_prompt": {
"$ref": "#/components/schemas/GenerateImageNegativePrompt"
}
}
}
}
}
}
}
},
"/v1/try-on": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Try On (Beta)",
"description": "**BETA** - This endpoint is currently in beta and may change without notice.
\nPlaces a garment onto a person image.
\n**For Best Results:**\n - Person Image:\n - There should only be one person in the image.\n - Plain backgrounds and no accessories are best\n - The person should take up most of the frame, a 3/4 body view works best.\n - The person should be standing facing forward, side/seated views work less well.\n - Garment Image:\n - The garment image should only contain a single garment.\n - Plain \"stock photos\" of garments work best, however the model is capable of transferring garments from one person to another.\n - The garment should take up most of the frame.\n - **Note:** If the garment image contains a person wearing the garment or other objects, garment extraction will be required, which costs an additional 5 credits.\n\n**Limitations:**\n - The API may not work with all garments, it works best with top garments like t-shirts, blouses, etc.\n - Text and fine details in the garment image may not be reproduced perfectly in the resulting image.\n - Colors in the resulting image may be slightly different to the colors in the garment image.\n\n**Input Image Limits:**\n - Max size: 25MB\n - Min resolution: 64x64px\n - Max resolution: 6000x6000px\n",
"operationId": "try-on",
"responses": {
"200": {
"description": "Success - returned when wait_for_result is true and processing completes successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JpegImageJSONResponse"
}
}
}
},
"202": {
"description": "Accepted - returned when wait_for_result is false, indicates that processing has started.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"description": "A unique identifier for this job that can be used to check status.",
"example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
}
}
},
"headers": {
"Location": {
"description": "Endpoint to poll for job status",
"schema": {
"type": "string",
"example": "/v1/try-on/job/6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"403": {
"$ref": "#/components/responses/Error403"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
],
"parameters": [
{
"in": "header",
"name": "Accept",
"required": false,
"schema": {
"type": "string"
},
"description": "Acceptable response media type(s). `application/json`."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"person_image_url": {
"$ref": "#/components/schemas/TryOnPersonURLParameter"
},
"garment_image_url": {
"$ref": "#/components/schemas/TryOnGarmentURLParameter"
},
"garment_mode": {
"$ref": "#/components/schemas/GarmentModeParameter",
"deprecated": true
},
"preprocess_garment": {
"$ref": "#/components/schemas/PreprocessGarmentParameter"
},
"remove_background": {
"$ref": "#/components/schemas/RemoveBackgroundParameter"
},
"wait_for_result": {
"$ref": "#/components/schemas/WaitForResultParameter"
}
}
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"person_image_url": {
"$ref": "#/components/schemas/TryOnPersonURLParameter"
},
"person_image": {
"$ref": "#/components/schemas/BinaryImageParameter"
},
"garment_image_url": {
"$ref": "#/components/schemas/TryOnGarmentURLParameter"
},
"garment_image": {
"$ref": "#/components/schemas/BinaryImageParameter"
},
"garment_mode": {
"$ref": "#/components/schemas/GarmentModeParameter",
"deprecated": true
},
"preprocess_garment": {
"$ref": "#/components/schemas/PreprocessGarmentParameter"
},
"remove_background": {
"$ref": "#/components/schemas/RemoveBackgroundParameter"
},
"wait_for_result": {
"$ref": "#/components/schemas/WaitForResultParameter"
}
}
}
}
}
}
}
},
"/v1/try-on/job/{jobId}": {
"get": {
"tags": [
"Endpoints"
],
"summary": "Try On Job Status (Beta)",
"description": "**BETA** - This endpoint is currently in beta and may change without notice.
\nChecks the status of a Try On job.\nWhen using the Try On API with wait_for_result set to false, it returns a job ID. This endpoint allows you to check the status of that job and retrieve the final result when processing is complete.\n",
"operationId": "try-on-job-status",
"parameters": [
{
"name": "jobId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the job to check"
}
],
"responses": {
"200": {
"description": "Job status retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"description": "The ID of the job",
"example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
},
"status": {
"type": "string",
"description": "The current status of the job",
"enum": [
"pending",
"running",
"completed",
"failed"
],
"example": "completed"
},
"result_url": {
"type": "string",
"description": "A URL to access the resultant image, only present when status is 'completed'",
"example": "https://assets.pixelcut.app/public/result/a16646be-91c8-4e3a-b359.jpg"
},
"error": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A description of the error.",
"example": "Job processing failed"
},
"error_code": {
"type": "string",
"enum": [
"invalid_parameter",
"content_filter_error",
"request_timeout",
"job_expired",
"job_cancelled",
"unexpected_error",
"service_unavailable"
],
"example": "content_filter_error",
"description": "The error codes provide a way to programmatically handle errors. \n\nThe following error codes are currently in use: \n- `invalid_parameter`: The request contained invalid parameters.\n- `content_filter_error`: The content was flagged by our content filter.\n- `request_timeout`: The request timed out while processing.\n- `job_expired`: The job has expired and is no longer available.\n- `job_cancelled`: The job was cancelled.\n- `unexpected_error`: An unexpected error occurred during processing.\n- `service_unavailable`: The service is temporarily unavailable.\n"
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"404": {
"$ref": "#/components/responses/Error404"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:read"
]
}
]
}
},
"/v1/try-on/job/{jobId}/cancel": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Try On Job Cancel (Beta)",
"description": "**BETA** - This endpoint is currently in beta and may change without notice.
\nCancels a Try On job that is currently pending or running.\nWhen a Try On job is submitted with wait_for_result set to false, it can be cancelled using this endpoint if it hasn't completed yet. Jobs that are already completed or failed cannot be cancelled.\n",
"operationId": "try-on-job-cancel",
"parameters": [
{
"name": "jobId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the job to cancel"
}
],
"responses": {
"200": {
"description": "Job cancelled successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Confirmation message",
"example": "Job cancelled"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Error401"
},
"404": {
"$ref": "#/components/responses/Error404"
},
"409": {
"description": "Job has already finished and cannot be canceled",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Job has already finished and cannot be canceled"
},
"error_code": {
"type": "string",
"enum": [
"job_finished"
],
"example": "job_finished"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
]
}
},
"/v1/video/remove-background": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Remove Video Background",
"description": "Removes the background from a video and optionally replaces it with a solid color or makes it transparent.
\n**Input Video Limits:**\n - Max size: 100MB\n - Max duration: 60 seconds\n - Supported formats: MP4, MOV, WebM, MKV, GIF\n - Supported codecs: H.264, H.265/HEVC, VP8, VP9, AV1, ProRes\n - Resolution: 64x64 to 4096x4096 pixels\n",
"operationId": "video-remove-background",
"responses": {
"202": {
"description": "Accepted - processing has started",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"description": "A unique identifier for this job that can be used to check status.",
"example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
}
}
},
"headers": {
"Location": {
"description": "Endpoint to poll for job status",
"schema": {
"type": "string",
"example": "/v1/video/remove-background/job/6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"403": {
"$ref": "#/components/responses/Error403"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"video_url"
],
"properties": {
"video_url": {
"$ref": "#/components/schemas/VideoURLParameter"
},
"background_color": {
"$ref": "#/components/schemas/VideoBackgroundColorParameter"
},
"output_format": {
"$ref": "#/components/schemas/VideoOutputFormatParameter"
}
}
}
}
}
}
}
},
"/v1/video/remove-background/job/{jobId}": {
"get": {
"tags": [
"Endpoints"
],
"summary": "Video Remove Background Job Status",
"description": "Checks the status of a Video Remove Background job.\nWhen using the Video Remove Background API, it returns a job ID. This endpoint allows you to check the status of that job and retrieve the final result when processing is complete.\n",
"operationId": "video-remove-background-job-status",
"parameters": [
{
"name": "jobId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the job to check"
}
],
"responses": {
"200": {
"description": "Job status retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"description": "The ID of the job",
"example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
},
"status": {
"type": "string",
"description": "The current status of the job",
"enum": [
"pending",
"running",
"completed",
"failed"
],
"example": "completed"
},
"result_url": {
"type": "string",
"description": "A URL to access the resultant video, only present when status is 'completed'",
"example": "https://assets.pixelcut.app/public/result/video-abc123.mp4"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "unexpected_error"
},
"message": {
"type": "string",
"description": "Error description",
"example": "Job processing failed"
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"404": {
"$ref": "#/components/responses/Error404"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:read"
]
}
]
}
},
"/v1/video/remove-background/job/{jobId}/cancel": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Cancel Video Remove Background Job",
"description": "Cancels a Video Remove Background job that is currently pending or running.\nJobs that are already completed or failed cannot be cancelled.\n",
"operationId": "video-remove-background-job-cancel",
"parameters": [
{
"name": "jobId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the job to cancel"
}
],
"responses": {
"200": {
"description": "Job cancelled successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Confirmation message",
"example": "Job cancelled"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Error401"
},
"404": {
"$ref": "#/components/responses/Error404"
},
"409": {
"description": "Job has already finished and cannot be canceled",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Job has already finished and cannot be canceled"
},
"error_code": {
"type": "string",
"enum": [
"job_finished"
],
"example": "job_finished"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
]
}
},
"/v1/video/loop": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Looping Video",
"description": "Turns a single still image into a seamless 5-15 second looping MP4 video. The subject, composition, and lighting are preserved, and the video loops endlessly with no visible jump or cut. The camera stays fixed - no pans, zooms, tilts, or reframing. Choose the motion style with `motion`: `subtle` (default) adds gentle, natural movement, while `spin` shows the subject from every side through a full 360-degree revolution that ends on the starting view. Processing is asynchronous: poll the job status endpoint returned in the `Location` header to retrieve the result.
\nProvide exactly one image source: a multipart `image` file, a base64/data-URL `image`, or a remote `image_url`. Requests with no image source or more than one are rejected.
\n**Pricing:**\n - 480p: 8 credits (\\$0.08) per second\n - 768p: 16 credits (\\$0.16) per second\n - 1080p: 32 credits (\\$0.32) per second\n - Audio does not change the price.
\n\n**Input Image Limits:**\n - Max size: 25MB\n - Min resolution: 64x64px\n - Max resolution: 6000x6000px\n - Supported formats: JPEG, PNG\n",
"operationId": "video-loop",
"responses": {
"202": {
"description": "Accepted - processing has started",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"description": "A unique identifier for this job that can be used to check status.",
"example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
},
"status": {
"type": "string",
"enum": [
"pending"
],
"description": "Initial job status.",
"example": "pending"
}
}
}
}
},
"headers": {
"Location": {
"description": "Endpoint to poll for job status",
"schema": {
"type": "string",
"example": "/v1/video/loop/job/6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"403": {
"$ref": "#/components/responses/Error403"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"image": {
"$ref": "#/components/schemas/Base64ImageParameter"
},
"prompt": {
"$ref": "#/components/schemas/LoopPromptParameter"
},
"duration": {
"$ref": "#/components/schemas/LoopDurationParameter"
},
"resolution": {
"$ref": "#/components/schemas/LoopResolutionParameter"
},
"include_audio": {
"$ref": "#/components/schemas/LoopIncludeAudioParameter"
},
"motion": {
"$ref": "#/components/schemas/LoopMotionParameter"
}
}
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"image": {
"$ref": "#/components/schemas/BinaryImageParameter"
},
"image_url": {
"$ref": "#/components/schemas/ImageURLParameter"
},
"prompt": {
"$ref": "#/components/schemas/LoopPromptParameter"
},
"duration": {
"$ref": "#/components/schemas/LoopDurationParameter"
},
"resolution": {
"$ref": "#/components/schemas/LoopResolutionParameter"
},
"include_audio": {
"$ref": "#/components/schemas/LoopIncludeAudioParameter"
},
"motion": {
"$ref": "#/components/schemas/LoopMotionParameter"
}
}
}
}
}
}
}
},
"/v1/video/loop/job/{jobId}": {
"get": {
"tags": [
"Endpoints"
],
"summary": "Looping Video Job Status",
"description": "Checks the status of a Looping Video job.\nWhen a job completes, the response includes a `result_url` pointing to the generated MP4. If the job was submitted with `include_audio: false`, the MP4 is guaranteed to contain no audio stream.\n",
"operationId": "video-loop-job-status",
"parameters": [
{
"name": "jobId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the job to check"
}
],
"responses": {
"200": {
"description": "Job status retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"description": "The ID of the job",
"example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
},
"status": {
"type": "string",
"description": "The current status of the job",
"enum": [
"pending",
"running",
"completed",
"failed"
],
"example": "completed"
},
"result_url": {
"type": "string",
"description": "A URL to access the resultant MP4 video, only present when status is 'completed'",
"example": "https://assets.pixelcut.app/public/result/6ba7b810-9dad-11d1-80b4-00c04fd430c8.mp4"
},
"error": {
"type": "object",
"description": "Error details, only present when status is 'failed'",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "unexpected_error"
},
"message": {
"type": "string",
"description": "Error description",
"example": "Job processing failed"
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error400"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"404": {
"$ref": "#/components/responses/Error404"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:read"
]
}
]
}
},
"/v1/video/loop/job/{jobId}/cancel": {
"post": {
"tags": [
"Endpoints"
],
"summary": "Cancel Looping Video Job",
"description": "Cancels a Looping Video job that is currently pending or running.\nJobs that are already completed or failed cannot be cancelled.\n",
"operationId": "video-loop-job-cancel",
"parameters": [
{
"name": "jobId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the job to cancel"
}
],
"responses": {
"200": {
"description": "Job cancelled successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Confirmation message",
"example": "Job cancelled"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Error401"
},
"404": {
"$ref": "#/components/responses/Error404"
},
"409": {
"description": "Job has already finished and cannot be canceled",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Job has already finished and cannot be canceled"
},
"error_code": {
"type": "string",
"enum": [
"job_finished"
],
"example": "job_finished"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:write"
]
}
]
}
},
"/v1/credits": {
"get": {
"tags": [
"Endpoints"
],
"summary": "Get Credits",
"description": "Returns the number of credits remaining in your account.",
"operationId": "get-credits",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreditsJSONResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error401"
},
"429": {
"$ref": "#/components/responses/Error429"
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"pixa:read"
]
}
]
}
}
},
"components": {
"responses": {
"Error400": {
"description": "The input could not be processed, often returned when the input image exceeds API limits.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "A description of the error.",
"example": "File size too large"
},
"error_code": {
"type": "string",
"enum": [
"invalid_request_body",
"missing_parameter",
"invalid_parameter",
"unsupported_content_type",
"malformed_image",
"unsupported_image_format",
"file_size_too_large",
"resolution_too_high",
"unknown_foreground"
],
"example": "file_size_too_large",
"description": "The error codes provide a way to programmatically handle errors. \n\nThe following error codes are currently in use: \n- `invalid_request_body`: The request body was empty or invalid.\n- `missing_parameter`: A required parameter was not provided.\n- `invalid_parameter`: A parameter was provided but it was invalid.\n- `unsupported_content_type`: The content type of the request was not application/json or multipart/form-data.\n- `malformed_image`: The image could not be decoded.\n- `unsupported_image_format`: The image format is not supported.\n- `file_size_too_large`: The image file size is too large.\n- `resolution_too_high`: The image resolution is too high.\n- `unknown_foreground`: The foreground subject of the image could not be detected.\n"
}
}
}
}
}
},
"Error401": {
"description": "The authentication token is missing or invalid.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "API Token not found"
},
"error_code": {
"type": "string",
"enum": [
"invalid_auth_token"
]
}
}
}
}
}
},
"Error403": {
"description": "Returned when you have insufficient credits to perform the requested action.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Insufficient credits available"
},
"error_code": {
"type": "string",
"enum": [
"insufficient_api_credits"
]
}
}
}
}
}
},
"Error404": {
"description": "Job not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Job not found"
},
"error_code": {
"type": "string",
"enum": [
"not_found"
]
}
}
}
}
}
},
"Error429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Too many requests"
},
"error_code": {
"type": "string",
"enum": [
"rate_limit_exceeded"
]
}
}
}
}
}
},
"Error500": {
"description": "Internal service error"
}
},
"schemas": {
"SameTypeAsRequestBinaryResponse": {
"type": "string",
"format": "binary",
"properties": {
"image": {
"description": "Resultant image in binary format. The file format will be the same as the input format."
}
}
},
"JpegBinaryResponse": {
"type": "string",
"format": "binary",
"properties": {
"image": {
"description": "Resultant image in binary format. The file format will be jpeg."
}
}
},
"PngBinaryResponse": {
"type": "string",
"format": "binary",
"properties": {
"image": {
"description": "Resultant image in binary format. The file format will be png."
}
}
},
"SameTypeAsRequestJSONResponse": {
"type": "object",
"properties": {
"result_url": {
"type": "string",
"description": "A URL to access the resultant image. The file is deleted after at most 24 hours. File format will be the same as the input format.",
"example": "https://assets.pixelcut.app/public/result/a16646be-91c8-4e3a-b359.jpg"
}
}
},
"JpegImageJSONResponse": {
"type": "object",
"properties": {
"result_url": {
"type": "string",
"description": "A URL to access the resultant image. The file is deleted after at most 24 hours. File format will be jpeg.",
"example": "https://assets.pixelcut.app/public/result/a16646be-91c8-4e3a-b359.jpg"
}
}
},
"PngImageJSONResponse": {
"type": "object",
"properties": {
"result_url": {
"type": "string",
"description": "A URL to access the resultant image. The file is deleted after at most 24 hours. File format will be png.",
"example": "https://assets.pixelcut.app/public/result/a16646be-91c8-4e3a-b359.png"
}
}
},
"CreditsJSONResponse": {
"type": "object",
"properties": {
"credits_remaining": {
"type": "string",
"description": "The number of credits remaining in your account.",
"example": 42
}
}
},
"Base64ImageParameter": {
"type": "string",
"format": "base64",
"description": "Base64 encoded representation of the image to be processed.",
"example": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/......"
},
"ImageURLParameter": {
"type": "string",
"format": "url",
"description": "URL of the image to be processed.",
"example": "https://cdn3.pixelcut.app/product.jpg"
},
"MaskURLParameter": {
"type": "string",
"format": "url",
"description": "URL of the mask to be processed.",
"example": "https://cdn3.pixelcut.app/product-mask.png"
},
"Base64MaskParameter": {
"type": "string",
"format": "base64",
"description": "Base64 encoded representation of the masked region. The mask should be the same size as the input image. It should contain non-zero pixels in the areas that should be processed and zero (black) pixels everywhere else.",
"example": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/......"
},
"BinaryImageParameter": {
"type": "string",
"format": "binary",
"description": "Binary file of the image to be processed, this is mutually exclusive with image_url, if both are provided the image will be used."
},
"BinaryMaskParameter": {
"type": "string",
"format": "binary",
"description": "Binary file of the masked region. The mask should be the same size as the input image. It should contain non-zero pixels in the areas that should be processed and zero (black) pixels everywhere else."
},
"ScaleParameter": {
"type": "integer",
"format": "int32",
"enum": [
2,
4
],
"description": "The scale factor."
},
"ImageFormatParameter": {
"type": "string",
"format": "string",
"enum": [
"png"
],
"description": "The format of the resultant image. Currently, only png is supported."
},
"GenerateImageBase64Parameter": {
"type": "string",
"format": "base64",
"description": "Base64 data uri of the image. If the image is RGB the background will automatically be removed, if the image is RGBA the background will not be removed and the alpha channel will be respected.",
"example": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/......"
},
"GenerateImageURLParameter": {
"type": "string",
"format": "url",
"description": "URL of the image. If the image is RGB the background will automatically be removed, if the image is RGBA the background will not be removed and the alpha channel will be respected.",
"example": "https://cdn3.pixelcut.app/product.jpg"
},
"TryOnPersonURLParameter": {
"type": "string",
"format": "url",
"description": "URL of the person's image.",
"example": "https://cdn3.pixelcut.app/virtual-try-on/person.png"
},
"TryOnGarmentURLParameter": {
"type": "string",
"format": "url",
"description": "URL of the garment image.",
"example": "https://cdn3.pixelcut.app/virtual-try-on/garment.png"
},
"GenerateImageBinaryParameter": {
"type": "string",
"format": "binary",
"description": "Binary file of the image. If the image is RGB the background will automatically be removed, if the image is RGBA the background will not be removed and the alpha channel will be respected.",
"example": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/......"
},
"ImageTransform": {
"type": "object",
"properties": {
"scale": {
"type": "number",
"default": 1,
"description": "Scales the input image. Scale of 1 means the longest edge of the image fits the canvas, 1 is the default value if the background was not removed automatically. If the background was removed, the alpha around the subject is automatically trimmed so we use a scale of 0.6 to provide padding around the subject in the final image."
},
"x_center": {
"type": "number",
"default": 0.5,
"description": "Positions the horizontal center of the image within the canvas. Ranges from 0 to 1."
},
"y_center": {
"type": "number",
"default": 0.5,
"description": "Positions the vertical center of the image within the canvas. Ranges from 0 to 1."
}
}
},
"GenerateImageNegativePrompt": {
"type": "string",
"format": "string",
"description": "A comma seperated list of attributes which should be discouraged in the image generation."
},
"GenerateImagePrompt": {
"type": "string",
"format": "string",
"description": "A description of the desired scene used to guide the image generation process."
},
"GenerateImageScene": {
"type": "string",
"format": "string",
"enum": [
"marble",
"wood",
"industrial",
"linen",
"brick",
"counter"
],
"description": "Select a preset scene type. If provided prompt and negative_prompt will be ignored."
},
"GarmentModeParameter": {
"type": "string",
"enum": [
"auto",
"full",
"upper",
"lower"
],
"default": "auto",
"deprecated": true,
"description": "> **⚠️ DEPRECATED**: This parameter is deprecated and will be removed in a future version.\n>\n> The API now automatically detects garment type without requiring manual specification.\n\nIndicates the garment type for the try-on service. Determines how the garment is applied on the person image.
- auto: Automatically detects if the garment is full-body, upper-body, or lower-body.
- full: Garment covers the full body (e.g., dresses, jumpsuits).
- upper: Garment covers the upper body (e.g., shirts, jackets).
- lower: Garment covers the lower body (e.g., pants, skirts).\n"
},
"PreprocessGarmentParameter": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "true",
"description": "When true, the garment will be preprocessed to remove background. Defaults to true. In some cases results of model will be improved by skipping pre-processing."
},
"RemoveBackgroundParameter": {
"type": "string",
"description": "When true, the background will be removed from the final result. Defaults to false.",
"enum": [
"true",
"false"
],
"default": "false"
},
"WaitForResultParameter": {
"type": "string",
"description": "When true, the API will wait for processing to complete and return the result directly. When false, it returns a job ID for polling.",
"default": "true",
"enum": [
"true",
"false"
]
},
"ShadowParameter": {
"description": "Enable and configure AI-generated shadow. When enabled, +3 credits are consumed. Pass `true` for automatic shadow estimation or provide a light source for custom control.\n",
"properties": {
"enabled": {
"type": "boolean",
"default": false,
"description": "Enable AI shadow rendering."
},
"opacity": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"default": 0.5,
"description": "Final composited shadow opacity (0–1)."
},
"light_source": {
"$ref": "#/components/schemas/ShadowLightSource"
}
},
"required": [
"enabled"
]
},
"ShadowLightSource": {
"type": "object",
"description": "Virtual light used to synthesize the shadow. x/y are normalized to image center (-1..1); z is height above subject (0..2).\n",
"properties": {
"size": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"default": 0.3,
"description": "Apparent emitter size/softness. Higher = softer penumbra."
},
"position": {
"type": "object",
"properties": {
"x": {
"type": "number",
"format": "float",
"minimum": -1,
"maximum": 1,
"default": -0.3
},
"y": {
"type": "number",
"format": "float",
"minimum": -1,
"maximum": 1,
"default": -0.6
},
"z": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 2,
"default": 0.7
}
},
"required": [
"x",
"y",
"z"
]
}
},
"required": [
"size",
"position"
]
},
"MarginParameter": {
"type": "string",
"description": "(Beta) General margin applied to all sides when crop is enabled. Only applies if crop is true. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).\n",
"example": "100px"
},
"DirectionalMarginParameter": {
"type": "string",
"description": "(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).\n",
"example": "50px"
},
"CropParameter": {
"type": "boolean",
"description": "When true, crops the image to the region of interest (the detected subject).\n",
"default": false
},
"OutpaintPixelParameter": {
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 2000,
"default": 0,
"description": "Number of pixels to extend the image in this direction (0-2000)."
},
"OutpaintCreativityParameter": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"default": 0,
"description": "Controls the creativity of the generated content. Higher values produce more creative but potentially less coherent results. 0 means maximum coherence, 1 means maximum creativity."
},
"OutpaintOutputFormatParameter": {
"type": "string",
"enum": [
"jpeg",
"png"
],
"default": "jpeg",
"description": "The format of the output image. Default is jpeg."
},
"LoopPromptParameter": {
"type": "string",
"maxLength": 1000,
"description": "Optional creative direction for the motion (e.g. what should move subtly). Directions requesting camera movement, cuts, new objects, or scene changes are ignored.",
"example": "clothes blowing subtly in the wind, person slightly moving"
},
"LoopDurationParameter": {
"type": "integer",
"format": "int32",
"minimum": 5,
"maximum": 15,
"default": 5,
"description": "Length of the looping video in whole seconds (5-15).",
"example": 5
},
"LoopResolutionParameter": {
"type": "string",
"enum": [
"480p",
"768p",
"1080p"
],
"default": "768p",
"description": "Output resolution of the looping video. 480p costs 8 credits per second; 768p costs 16 credits per second; 1080p costs 32 credits per second.",
"example": "768p"
},
"LoopIncludeAudioParameter": {
"type": "boolean",
"default": true,
"description": "Whether the generated MP4 keeps its audio track. When false, the audio track is stripped and the result is guaranteed to contain no audio stream. Audio does not change the price.",
"example": true
},
"LoopMotionParameter": {
"type": "string",
"enum": [
"subtle",
"spin"
],
"default": "subtle",
"description": "Motion style. `subtle` adds gentle, natural movement that returns to the starting pose. `spin` shows the subject from every side through one full 360-degree revolution that ends on the starting view. People and isolated products on a plain background turn in place while the camera stays fixed; an object photographed in a real setting stays still and the camera orbits around it instead. Does not change the price.",
"example": "subtle"
},
"VideoURLParameter": {
"type": "string",
"format": "url",
"description": "URL of the video to be processed. Must be a publicly accessible URL.",
"example": "https://example.com/video.mp4"
},
"VideoBackgroundColorParameter": {
"type": "string",
"pattern": "^(transparent|#[0-9A-Fa-f]{3}|#[0-9A-Fa-f]{6})$",
"default": "#000000",
"description": "The background color to use after removal.\n- Use \"transparent\" for transparent background (requires webm_vp9, mov_h265, mov_proresks, or gif output format)\n- Use hex code (e.g., \"#000000\", \"#FF5733\") for solid color\n"
},
"VideoOutputFormatParameter": {
"type": "string",
"enum": [
"mp4_h264",
"mp4_h265",
"webm_vp9",
"mov_h265",
"mov_proresks",
"mkv_h264",
"mkv_h265",
"mkv_vp9",
"gif"
],
"default": "mp4_h264",
"description": "Output video format with codec specification. Defaults to `mp4_h264` if not specified.\n\n**Formats:**\n- mp4_h264: MP4 with H.264 codec\n- mp4_h265: MP4 with H.265/HEVC codec\n- webm_vp9: WebM with VP9 codec (supports transparency)\n- mov_h265: QuickTime with H.265 codec (supports transparency)\n- mov_proresks: QuickTime with ProRes 4444 codec (supports transparency)\n- mkv_h264: Matroska with H.264 codec\n- mkv_h265: Matroska with H.265 codec\n- mkv_vp9: Matroska with VP9 codec\n- gif: Animated GIF (supports transparency)\n"
}
},
"securitySchemes": {
"ApiKeyAuth": {
"description": "All API requests require a valid api key. Include your token as a HTTP request header in the following format: `X-API-Key: skXXXXXXXXXXXXXXXX`. You can obtain an api key by signing up for developer access in your Pixelcut account.\n",
"type": "apiKey",
"name": "X-API-KEY",
"in": "header"
},
"OAuth2": {
"description": "OAuth 2.0 authorization code flow, used by MCP clients and third-party integrations acting on a user's behalf. Request the narrowest scope your integration needs.\n",
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://oauth.pixelcut.ai/oauth/authorize",
"tokenUrl": "https://oauth.pixelcut.ai/oauth/token",
"refreshUrl": "https://oauth.pixelcut.ai/oauth/token",
"scopes": {
"pixa:read": "Read account state — credit balance, job status, and previously generated assets.",
"pixa:write": "Submit editing and generation jobs that consume credits."
}
}
}
}
}
}
}