Picsart Editing API
The Editing API from Picsart — 4 operation(s) for editing.
The Editing API from Picsart — 4 operation(s) for editing.
openapi: 3.0.0
info:
version: '1.0'
title: Picsart GenAI Ads Editing API
description: '[Official technical documentation portal](https://docs.picsart.io/)
[Developer Guidelines](https://picsart.io/terms)
'
servers:
- url: https://genai-api.picsart.io/v1
description: Production
security:
- apiKey: []
tags:
- name: Editing
paths:
/edit:
post:
summary: Basic Editing
operationId: image-edit
description: 'The *Edit* service applies basic image editing to an input image. The basic editing operations are resize, crop, flip, rotate and perspective manipulation.
'
tags:
- Editing
requestBody:
content:
multipart/form-data:
schema:
allOf:
- $ref: '#/components/schemas/ImageParameters'
- $ref: '#/components/schemas/EditParameters'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'402':
$ref: '#/components/responses/402'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'413':
$ref: '#/components/responses/413'
'415':
$ref: '#/components/responses/415'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'431':
$ref: '#/components/responses/431'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
/smart-crop:
post:
summary: Smart Crop
operationId: image-smart-crop
description: 'Use AI to define the segment that should be cropped, e.g. foreground or product name (e.g. hat, gloves, boots, etc).
'
tags:
- Editing
requestBody:
content:
multipart/form-data:
schema:
allOf:
- $ref: '#/components/schemas/ImageParameters'
- $ref: '#/components/schemas/SmartCropParameters'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'402':
$ref: '#/components/responses/402'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'413':
$ref: '#/components/responses/413'
'415':
$ref: '#/components/responses/415'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'431':
$ref: '#/components/responses/431'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
/blend:
post:
summary: Blending
operationId: image-blend
description: 'Whether you''re adding a custom watermark, layering in a texture, or composing multi-image layouts for eCommerce or social media, Blend service turns simple images into sophisticated visuals with just one call.
This endpoint lets you seamlessly combine a base image with another visual layer - like an overlay, mask, or logo - while giving you full control over how the two interact. Think of it as your virtual creative layer engine: the same power you''d expect from a professional design tool, now embedded into your workflow or platform.
No need for manual edits or complex graphic design tools. With the blend API, your app or service can automate visually rich output that''s both fast and fully customizable.
'
tags:
- Editing
requestBody:
content:
multipart/form-data:
schema:
allOf:
- $ref: '#/components/schemas/ImageParameters'
- $ref: '#/components/schemas/OverlayParameters'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'402':
$ref: '#/components/responses/402'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'413':
$ref: '#/components/responses/413'
'415':
$ref: '#/components/responses/415'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'431':
$ref: '#/components/responses/431'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
/zoom:
post:
summary: Zoom
operationId: image-zoom
description: 'Zoom your images with 1-75 scale factors.
'
tags:
- Editing
requestBody:
content:
multipart/form-data:
schema:
allOf:
- $ref: '#/components/schemas/ImageParameters'
- $ref: '#/components/schemas/ZoomParameters'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'402':
$ref: '#/components/responses/402'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'413':
$ref: '#/components/responses/413'
'415':
$ref: '#/components/responses/415'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'431':
$ref: '#/components/responses/431'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
components:
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401_Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'431':
description: Request Header Fields Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'413':
description: Request Entity Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
nullable: true
url:
type: string
format: uri
nullable: false
status:
type: string
nullable: false
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
'415':
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Picsart-Correlation-Id:
schema:
type: string
description: The id which will help for troubleshooting request chain in the system.
X-Picsart-Ratelimit-Available:
schema:
type: integer
description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Limit:
schema:
type: integer
description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
X-Picsart-Ratelimit-Reset-Time:
schema:
type: integer
description: The time when the used request count resets and the number of available calls gets equal to the total number.
X-Picsart-Credit-Available:
schema:
type: integer
description: The remaining number of the credits on the balance.
schemas:
EditParameters:
type: object
properties:
format:
type: string
default: JPG
enum:
- JPG
- PNG
- WEBP
description: "Optionally select one of the image formats (JPG is chosen if left blank). Options are as follows:\n * JPG\n * PNG\n * WEBP\n"
mode:
type: string
nullable: true
enum:
- resize
- crop
description: For *crop* mode, the outcome image will be center-cropped with the given size (width, height). For the *resize* mode, the smallest size will be fitted to preserve the original proportion of the image. When the outcome size is not provided with width and height, no cropping or resizing will be applied (see alternative options such as rotate, flip and perspective).
size:
type: integer
nullable: true
description: When defined, this parameter overrides and applies the value for both width and height.
width:
type: integer
description: Width of outcome image. If the provided width is larger than the original width of the file, the original size of the image will be selected. When crop size is defined, but the x,y starting position is not provided, the crop will be a center-crop (i.e., equally cutting from each side).
nullable: true
height:
type: integer
description: Height of outcome image. If the provided height is larger than the original width of the file, the original size of the image will be selected. When crop size is defined, but the x,y starting position is not provided, the crop will be a center-crop (i.e, equally cutting from each side).
nullable: true
crop_x:
type: integer
nullable: true
description: 'crop_x, toghether with crop_y, define the anchor point of the crop. This point will be the center of the crop area. The top-left corner corresponds to (0,0) point and the bottom-right corner corresponds to (widht,height) point.
'
crop_y:
type: integer
nullable: true
description: 'crop_y, toghether with crop_x, define the anchor point of the crop. This point will be the center of the crop area. The top-left corner corresponds to (0,0) point and the bottom-right corner corresponds to (widht,height) point.
'
crop_anchor:
type: string
enum:
- center
- top-left
- top-right
- bottom-left
- bottom-right
default: center
nullable: true
description: "By default when crop_anchor or crop_x,crop_y pair are not provided, the crop will be done around the center of the image. This parameter is an easier option to crop_x,crop_y pair where the respective corner of the image will be cropped. Options for crop anchor are as follows:\n * center\n * top-left\n * top-right\n * bottom-left\n * bottom-right\n"
flip:
type: string
enum:
- horizontal
- vertical
description: Choose a way to flip the image.
rotate:
type: number
format: float
default: 0.0
minimum: -180.0
maximum: 180.0
description: Enter a float value to rotate the image from -180 to +180. Default is 0.
perspective_horizontal:
type: integer
default: 0
minimum: -45
maximum: 45
description: The horizontal perspective after edits.
perspective_vertical:
type: integer
default: 0
minimum: -45
maximum: 45
description: The vertical perspective after edits.
quality:
type: integer
default: 90
minimum: 10
maximum: 100
description: This refers to the level of accuracy of the image processing. The greater the quality (i.e., the larger the number), the larger the image file size. The default value is 90, which is a good compromise between quality and file size.
OverlayParameters:
type: object
properties:
overlay_image:
description: Overlay image file (binary). (If this parameter is present, the other image source parameters must be empty.) This only has an effect when output=cutout.
type: string
format: binary
nullable: true
overlay_image_url:
type: string
nullable: true
description: Overlay image URL. (If this parameter is present, the other image source parameters must be empty.) If this has a value, the output value is dismissed.
maxLength: 2083
minLength: 1
format: uri
overlay_image_id:
type: string
nullable: true
deprecated: true
description: Deprecated. Overlay image ID of an image previously uploaded to Picsart or result image ID from a different API. (If this parameter is present, the other image source parameters must be empty.) See /upload method. If this has a value, the output value is dismissed.
opacity:
type: integer
nullable: true
default: 100
minimum: 0
maximum: 100
description: "Define the opacity of the overlay added to the main image.\n Takes values from 0 to 100. Default is 100 (opaque). Set to 0 to make it transparent.\n"
blend_mode:
type: string
enum:
- normal
- darken
- multiply
- lighten
- screen
- color_dodge
- overlay
- soft_light
- hard_light
- hue
- saturation
- color
- luminosity
nullable: true
default: normal
description: 'The blend mode. Choose one of normal, darken, multiply, lighten, screen, color_dodge, overlay, soft_light, hard_light, hue, saturation, color, luminosity. Defaults to normal.
'
format:
type: string
enum:
- JPG
- PNG
- WEBP
default: JPG
description: "Optionally select one of the image formats (JPG is chosen if left blank). Options are as follows:\n * JPG\n * PNG\n * WEBP\n"
SmartCropParameters:
required:
- segment
type: object
properties:
segment:
type: string
maxLength: 90
minLength: 1
description: 'The segment to crop.
Use either ''foreground'', or define the name of the segments such as ''hat'' or ''boots''.
Recommendation: use short and clear names of the segment (e.g. object or area). We don''t recommend using long prompts.
'
ratio:
type: string
enum:
- '1:1'
- '4:3'
- '3:2'
- '16:9'
- '21:9'
- '4:5'
- '9:16'
- '2:3'
- '5:4'
description: 'Optionally enforce the ration of the result image. When both width and height parameters are provided, they should match this ratio.
In case either width or height are provided, the other value will be calculated based on this ratio.
'
width:
type: integer
description: Specify the width of the output image in pixels.
minimum: 0
height:
type: integer
description: Specify the height of the output image in pixels. The default is 1024 and the maximum acceptable value is 8000.
minimum: 0
margin:
type: integer
minimum: 0
maximum: 100
description: 'The margin to add around the crop segment. Values are defined in pixels.
When ratio is provided, that is applied after the margin is applied to guarantee the minimum gap before the edge of the image.
'
default: 0
format:
type: string
default: JPG
enum:
- JPG
- PNG
- WEBP
description: "Optionally select one of the image formats. Options are as follows:\n * JPG\n * PNG\n * WEBP\n"
Error:
type: object
properties:
message:
type: string
detail:
type: string
required:
- detail
ZoomParameters:
required:
- scale_factor
type: object
properties:
scale_factor:
type: integer
minimum: 1
maximum: 75
description: The scale factor. 50 means 2x, and 75 means 1.5x.
default: 2
anchor_point:
type: string
default: center-middle
enum:
- left-top
- left-middle
- left-bottom
- center-top
- center-middle
- center-bottom
- right-top
- right-middle
- right-bottom
- ai
description: Anchor point for zooming. Determines which part of the image to focus on. Expect longer response times when 'ai' is used.
format:
type: string
default: JPG
enum:
- JPG
- PNG
- WEBP
description: "Optionally select one of the image formats. Options are as follows:\n * JPG\n * PNG\n * WEBP\n"
ImageParameters:
type: object
properties:
image:
description: Source image file (binary). (If this parameter is present, the other image source parameters must be empty.)
type: string
format: binary
image_url:
type: string
description: Source image URL. (If this parameter is present, the other image source parameters must be empty.)
maxLength: 2083
minLength: 1
format: uri
image_id:
type: string
deprecated: true
description: Deprecated. Source image ID of an image previously uploaded to Picsart or result image ID from a different API. (If this parameter is present, the other image source parameters must be empty.)
401_Error:
type: object
properties:
code:
type: integer
example: 401
message:
type
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/picsart/refs/heads/main/openapi/picsart-editing-api-openapi.yml