Photopea API

https://www.photopea.com/api
Admin
Photopea API enables developers to integrate Photopea's web-based photo editor into their...
Tokens:15,832
Snippets:189
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### PHP handler for Photopea save requests

Source: https://www.photopea.com/api

PHP example that accepts files from Photopea. It reads the 2000-byte JSON header from php://input, extracts the filename from the 'source' field, then writes the remaining binary data to an 'img/' directory. The script assumes the 'img' directory exists and is writable.

```php
$fi = fopen("php://input", "rb");  $p = JSON_decode(fread($fi, 2000));
// getting file name from "source"
$fname = substr ($p->source, strrpos($p->source,"/")+1);  
$fo = fopen("img/".$fname,"wb");  while($buf=fread($fi,50000)) fwrite($fo,$buf);
fclose($fi);  fclose($fo);
```

--------------------------------

### Script1.jsx variable assignment

Source: https://www.photopea.com/api/playground

Example code from a saved script1.jsx file that sets a variable a to 1.

```javascript
var a = 1;
```

--------------------------------

### Include JSX file and alert variable

Source: https://www.photopea.com/api/playground

Example of including a saved JSX file in another script and using its variable. This is a user question about including one saved JSX file in another.

```javascript
#include "script1.jsx"
alert(a);
```

--------------------------------

### Translate active layer

Source: https://www.photopea.com/api/playground

Translates the active layer by 20 pixels in both the x and y directions. This is a simple example of running a script in the Photopea API playground.

```javascript
app.activeDocument.activeLayer.translate(20,20);
```

--------------------------------

### JSON configuration for Photopea files

Source: https://www.photopea.com/api/playground

JSON object specifying files to open in Photopea. The user attempted to use this in the playground, but it failed due to CORS.

```json
{
  "files": [
    "https://storage.googleapis...."
  ],
  "environment": {
  }
}
```

--------------------------------

### Echo a string to outer environment

Source: https://www.photopea.com/api/live

Sends a string from Photopea to the outer environment. Use this to send arbitrary data back to the host page.

```javascript
app.echoToOE("Hello");
```

--------------------------------

### POST /save

Source: https://www.photopea.com/api

Documentation for the Photopea save-to-server endpoint, including request format, JSON metadata structure, and optional response parameters.

```APIDOC
## [POST] /save

### Description
Receives document data from Photopea when a user clicks File - Save. The request body contains binary data: 2000 bytes of JSON metadata followed by one or more image files.

### Method
POST

### Endpoint
Your server endpoint (specified via the `server` parameter in the Photopea request)

### Request Body
Binary data with two parts:
- 2000 Bytes - JSON data
- The rest - one or more image files

#### JSON Structure
- **source** (string) - URL of the document if loaded from your server; otherwise `"local,X,NAME"` where X is the integer document ID and NAME is the document name
- **versions** (array) - Different versions of the document
  - **format** (string) - Format of the exported file
  - **start** (integer) - File offset (relative to the end of JSON)
  - **size** (integer) - Size of the file

### Request Example
```
{
	"source" : "https://www.mysite.com/images/button.png",
	"versions" : [
		{"format":"psd", "start":      0, "size": 700000 },
		{"format":"jpg", "start": 700000, "size": 100000 },
		...
	]
}
```

### Response
#### Success Response (200)
Optional JSON parameters:
- **message** (string) - Displayed to the user for a moment
- **script** (string) - Executed (e.g., `app.echoToOE("saved");`)
- **newSource** (string) - New value of "source" for future saves

#### Response Example
```
{
  "message": "Saved successfully",
  "script": "app.echoToOE(\"saved\");",
  "newSource": "https://www.mysite.com/images/button.png"
}
```
```

--------------------------------

### Environment JSON for Move tool menu

Source: https://www.photopea.com/api/playground

Environment JSON that sets the tool-specific menu for the Move tool (t0) to an empty array, hiding its menu items.

```json
{
    "environment": {
         "tmnu": {"t0": []}
    }
 }
```

--------------------------------

### Listen for messages and send a message to Photopea

Source: https://www.photopea.com/api/live

Sets up a message listener and sends a message to the Photopea iframe. Use this to establish communication with Photopea from the outer environment.

```javascript
window.addEventListener("message", function(e) { alert(e.data); });
var wnd = document.getElementById("pp").contentWindow;
wnd.postMessage(msg, "*");
```

--------------------------------

### POST /script/echoToOE

Source: https://www.photopea.com/api/live

Sends a String from Photopea to the Outer Environment.

```APIDOC
## [POST] /script/echoToOE

### Description
Sends a String from Photopea to the Outer Environment.

### Method
POST

### Endpoint
/script/echoToOE

### Parameters
#### Request Body
- **message** (String) - Required - The string to send to the Outer Environment.

### Request Example
```javascript
app.echoToOE("Hello");
```

### Response
#### Success Response (200)
- **message** (String) - The string sent to the Outer Environment.
- **done** (String) - Sent after processing the script has finished.

#### Response Example
```javascript
window.addEventListener("message", function(e) { alert(e.data); });
```
```

--------------------------------

### Playground configuration with file URL

Source: https://www.photopea.com/api/playground

JSON configuration for the Photopea playground that specifies a file URL to load. The user reports that the iframe keeps showing a loading message when using a URL from another website.

```json
{
    "files": [ 
        "https://www.putorius.net/wp-content/uploads/2020/01/photopea-feat.jpg"  
    ],  
    "environment": {
  
    }  
}
```

--------------------------------

### Photopea URL with configuration string

Source: https://www.photopea.com/api

Use this URL format to pass a configuration string to Photopea. The string is encoded using standard query parameter encoding (e.g., spaces as %20), corresponding to encodeURIComponent() in JavaScript or urlencode() in PHP. The string must contain a JSON object.

```text
https://www.photopea.com#STRING_VALUE
```

--------------------------------

### Load image into Photopea with environment configuration

Source: https://www.photopea.com/api/environment

JavaScript object used to load an image into Photopea via the URL hash. The 'files' array contains the image URL, and 'environment' includes menu configuration. The user encountered CORS issues when loading images from a local server; the server must return the correct CORS headers.

```javascript
var jsobObj = {  
"files": [  
"https://localhost:44345/TempImage/036bb318-1ce4-4496-894f-8de4300dec3e.jpg"  
],  
"environment": {  
"menus": [0, 0, [1, 1, 1, 1, 1, 0, 0, [1, 1, 0, 1, 1], 1], 0],  
"tmnu": { "t0":"0,1" },
},
};
```

--------------------------------

### Environment JSON for Rectangle Selection tool menu

Source: https://www.photopea.com/api/playground

Environment JSON that sets the tool-specific menu for the Rectangle Selection tool (t1) to an empty array, but the menu does not disappear as expected.

```json
{
    "environment": {
         "tmnu": {"t1": []}
    }
 }
```

--------------------------------

### Live Messaging postMessage calls

Source: https://www.photopea.com/api/plugins

Live Messaging calls from a plugin website to Photopea. The first sends a script to execute, the second sends an ArrayBuffer (e.g., an image or resource file) to Photopea.

```javascript
window.parent.postMessage("...script...", "*");
window.parent.postMessage(ArrayBuffer, "*");
```

--------------------------------

### Plugin configuration JSON

Source: https://www.photopea.com/api/plugins

Configuration JSON for adding a plugin to Photopea. The plugin is defined by its name, URL, and optional icon. The 'w' and 'h' properties are optional but strongly discouraged; the plugin should work at any size.

```json
{ "environment": {
	"plugins" : [ 
		{
			"name"  : "Wikipedia",
			"url"   : "https://en.wikipedia.org",
			"icon"  : "https://en.wikipedia.org/static/favicon/wikipedia.ico"
		}
	]
} }
```

--------------------------------

### Photopea JSON configuration object

Source: https://www.photopea.com/api

JSON configuration object passed to Photopea via the URL hash. All parameters are optional. The files array can include data URIs to pass files inside the request. The server object controls saving documents back to a server, with formats corresponding to saveToOE. The apis object accepts third-party API keys, such as dezgo for Magic Replace and Remove BG, and dezgoURL to route Dezgo requests to a custom server (works only if dezgo is specified). The script parameter is executed after loading each file.

```json
{
	"files" : [
		"https://www.mysite.com/images/design.psd",
		"https://www.mysite.com/images/button.png",
		"data:image/png;base64,iVBORw0KGgoAAAAN..."
	],
	"resources" : [
		"https://www.xyz.com/brushes/Nature.ABR",
		"https://www.xyz.com/grads/Gradients.GRD",
		"https://www.xyz.com/fonts/NewFont.otf"
	],
	"server" : {
		"version" : 1,
		"url"     : "https://www.myserver.com/saveImage.php",
		"formats" : [ "psd:true", "png", "jpg:0.5" ]
	},
	"environment" : {...},
	"apis"   : { "dezgo": "d4e5f6", "dezgoURL":"https://www.mysite.com/"  },
	"script" : "app.activeDocument.rotateCanvas(90);"
}
```

--------------------------------

### Open image in Photopea

Source: https://www.photopea.com/api/playground

Use this script to open an image file in Photopea when it is already loaded in an iframe. The script is sent to Photopea for execution.

```javascript
app.open("image.jpg");
```

--------------------------------

### POST /message

Source: https://www.photopea.com/api/live

Sends a message to Photopea via Web Messaging. The message can be a String (a script to be executed) or an ArrayBuffer (a binary file).

```APIDOC
## [POST] /message

### Description
Sends a message to Photopea via Web Messaging. The message can be a String (a script to be executed) or an ArrayBuffer (a binary file).

### Method
POST

### Endpoint
/message

### Parameters
#### Request Body
- **message** (String or ArrayBuffer) - Required - The message to send to Photopea. A String contains a script to be executed; an ArrayBuffer contains a binary file (psd, svg, jpg, fonts, brushes, etc.).

### Request Example
```javascript
var wnd = document.getElementById("pp").contentWindow;
wnd.postMessage(msg, "*");
```

### Response
#### Success Response (200)
- **done** (String) - Sent by Photopea when it is initialized and ready to accept commands, and after each message is processed.

#### Response Example
```javascript
window.addEventListener("message", function(e) { alert(e.data); });
```
```

--------------------------------

### POST /script/saveToOE

Source: https://www.photopea.com/api/live

Sends the current image from Photopea to the Outer Environment as an ArrayBuffer of the specified format.

```APIDOC
## [POST] /script/saveToOE

### Description
Sends the current image from Photopea to the Outer Environment as an ArrayBuffer of the specified format.

### Method
POST

### Endpoint
/script/saveToOE

### Parameters
#### Request Body
- **format** (String) - Required - The format of the image to send (e.g., "gif").

### Request Example
```javascript
app.activeDocument.saveToOE("gif");
```

### Response
#### Success Response (200)
- **ArrayBuffer** - The image data in the specified format.
- **done** (String) - Sent after processing the script has finished.

#### Response Example
```javascript
window.addEventListener("message", function(e) { alert(e.data); });
```
```

--------------------------------

### Plugin gallery JSON structure

Source: https://www.photopea.com/api/plugins

JSON structure for a plugin file to be uploaded to the public plugin gallery via Window - Plugins - Add Plugin. The plugin and icon must remain at the same URL for future updates.

```json
{  "name":"...", "url":"...", "icon":"..."  }
```

--------------------------------

### Save current image to outer environment

Source: https://www.photopea.com/api/live

Sends the current image from Photopea to the outer environment as an ArrayBuffer. After running, Photopea sends a message with the image data followed by a "done" message.

```javascript
app.activeDocument.saveToOE("gif");
```

--------------------------------

### Load image into Photopea iframe with JSON hash

Source: https://www.photopea.com/api/environment

Function that loads an image into Photopea by setting the iframe's src to the Photopea URL with a JSON payload in the hash. It includes a random query parameter to avoid caching. The user reported CORS issues when loading images from a local server; the server must return the correct CORS headers.

```javascript
function loadSelectedImage() {
var jsobObj = {  
"files": [  
"https://localhost:44345/TempImage/036bb318-1ce4-4496-894f-8de4300dec3e.jpg"
],  
"environment": {  
"menus": [0, 0, [1, 1, 1, 1, 1, 0, 0, [1, 1, 0, 1, 1], 1], 0],  
"tmnu": { "t0":"0,1" },
},
};  
var json = jsobObj;  
json = JSON.stringify(json);  
var url = "https://www.photopea.com";  
var end = "#" + encodeURI(json);  
frame = document.getElementById("photopea");  
frame.src = url + "?rnd=" + Math.floor(Math.random() * 0xffffffff) + end;
}
```

--------------------------------

### Set CORS header Access-Control-Allow-Origin

Source: https://www.photopea.com/api

Required response header for the server hosting the file to allow Photopea to load it from a different domain. Without this header, the browser blocks the request due to same-origin policy.

```http
Access-Control-Allow-Origin: *
```

--------------------------------

### Photopea script output

Source: https://www.photopea.com/api/playground

Output messages from Photopea after running a script. The repeated 'done' messages indicate successful execution.

```text
done
done

```

--------------------------------

### Add CORS header in .htaccess

Source: https://www.photopea.com/api/playground

Adds the Access-Control-Allow-Origin header to allow cross-origin requests. Use this in the .htaccess file of your web server to enable Photopea to load images from your domain.

```apache
<ifmodule mod_headers.c="">
              Header set Access-Control-Allow-Origin "*"
  </ifmodule>
```

--------------------------------

### Embed Photopea with iframe

Source: https://www.photopea.com/api/live

Embeds the free version of Photopea in a webpage using an iframe. The src attribute points to the Photopea website.

```html
<iframe src="https://www.Photopea.com"></iframe>
```

--------------------------------

### Rename active document in Photopea

Source: https://www.photopea.com/api/live

Changes the name of the active document in Photopea to "Hello". This is used to assign a custom name to an image instead of the default 'image'.

```javascript
app.activeDocument.name="Hello";
```

--------------------------------

### Photopea save request JSON structure

Source: https://www.photopea.com/api

JSON structure sent by Photopea to your server when a user saves a document. The first 2000 bytes of the POST body contain this JSON, followed by one or more image files. The 'source' field is the document URL or 'local,X,NAME' for local files; 'versions' lists each exported file with its format and byte offset/size relative to the end of the JSON.

```json
{
	"source" : "https://www.mysite.com/images/button.png",
	"versions" : [
		{"format":"psd", "start":      0, "size": 700000 },
		{"format":"jpg", "start": 700000, "size": 100000 },
		...
	]
}
```
Tokens:
Raw