Edit an image

curl --request POST \
  --url https://api.meshapi.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "openai/gpt-image-1",
  "prompt": "Add a red scarf to the portrait",
  "image": {
    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }
}
'

import requests

url = "https://api.meshapi.ai/v1/images/edits"

payload = {
    "model": "openai/gpt-image-1",
    "prompt": "Add a red scarf to the portrait",
    "image": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'openai/gpt-image-1',
    prompt: 'Add a red scarf to the portrait',
    image: {
      url: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='
    }
  })
};

fetch('https://api.meshapi.ai/v1/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.meshapi.ai/v1/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'openai/gpt-image-1',
    'prompt' => 'Add a red scarf to the portrait',
    'image' => [
        'url' => 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.meshapi.ai/v1/images/edits"

	payload := strings.NewReader("{\n  \"model\": \"openai/gpt-image-1\",\n  \"prompt\": \"Add a red scarf to the portrait\",\n  \"image\": {\n    \"url\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.meshapi.ai/v1/images/edits")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"openai/gpt-image-1\",\n  \"prompt\": \"Add a red scarf to the portrait\",\n  \"image\": {\n    \"url\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.meshapi.ai/v1/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"openai/gpt-image-1\",\n  \"prompt\": \"Add a red scarf to the portrait\",\n  \"image\": {\n    \"url\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "created": 1717200000,
  "data": [
    {
      "url": "https://images.example.com/edits/portrait-with-scarf.png"
    }
  ]
}

Images

Edit an image

OpenAI-compatible image editing endpoint. Accepts EITHER ``multipart/form-data`` (binary uploads: ``image``, optional ``mask``, ``reference_images``) OR ``application/json`` whose image fields are data-URL / base64 strings (or ``{"url": ...}`` objects) — the same convention as the chat ``image_url``. Remote http(s) URLs are rejected (mesh does not server-side-fetch images); send a ``data:image/<fmt>;base64,<data>`` URL. Supports ``operation`` in {edit, remove_background, upscale, outpaint, mix, reframe, inpaint}. Each op is gated by the resolved model's supports_image_<op> flag (422 when unset / unsupported); the legacy provider matrix is a transitional backstop for the original four ops. - ``edit`` (default): openai, byteplus, vertex — prompt + image (+ optional mask + refs). - ``remove_background``: openai, vertex — image only; prompt optional. - ``upscale``: vertex (Imagen) or byteplus (Seedream Smart Upscale) — image + upscale_factor (x2|x4; Seedream maps x2→2k, x4→4k). - ``outpaint``: vertex — image + prompt + mask (defines expansion region). - ``mix``: Gemini image models + gpt-image (openai) — prompt + image + 1-3 reference_images (2-4 sources composed into one, sent as image[]); single output. - ``reframe``: Gemini image models — image + aspect_ratio (1:1|3:4|4:3|9:16|16:9|2:3|3:2); recomposes by outpainting to the target ratio; single output. - ``inpaint``: openai, vertex — image + mask (canonical WHITE=edit; mesh normalizes per provider). Optional mask_feather blends the result back through the mask (Pillow; 501 if unavailable). > **Note:** The image response may not render in GitBook's "Test it" panel. > To view the edited image, try this endpoint with Postman, curl, or another > HTTP client.

POST

images

edits

Edit an image

curl --request POST \
  --url https://api.meshapi.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "openai/gpt-image-1",
  "prompt": "Add a red scarf to the portrait",
  "image": {
    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }
}
'

import requests

url = "https://api.meshapi.ai/v1/images/edits"

payload = {
    "model": "openai/gpt-image-1",
    "prompt": "Add a red scarf to the portrait",
    "image": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'openai/gpt-image-1',
    prompt: 'Add a red scarf to the portrait',
    image: {
      url: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='
    }
  })
};

fetch('https://api.meshapi.ai/v1/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.meshapi.ai/v1/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'openai/gpt-image-1',
    'prompt' => 'Add a red scarf to the portrait',
    'image' => [
        'url' => 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.meshapi.ai/v1/images/edits"

	payload := strings.NewReader("{\n  \"model\": \"openai/gpt-image-1\",\n  \"prompt\": \"Add a red scarf to the portrait\",\n  \"image\": {\n    \"url\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.meshapi.ai/v1/images/edits")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"openai/gpt-image-1\",\n  \"prompt\": \"Add a red scarf to the portrait\",\n  \"image\": {\n    \"url\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.meshapi.ai/v1/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"openai/gpt-image-1\",\n  \"prompt\": \"Add a red scarf to the portrait\",\n  \"image\": {\n    \"url\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "created": 1717200000,
  "data": [
    {
      "url": "https://images.example.com/edits/portrait-with-scarf.png"
    }
  ]
}

Authorizations

Authorization

string

header

required

Enter your MeshAPI key (rsk_...) — sent as Authorization: Bearer <key>.

Headers

X-Mesh-Version

enum<string>

default:2026-08

Dated version of the API contract to pin this request to. Omit it and the request is served under 2026-08 — the oldest supported version, so an existing integration is never moved by a release. A malformed or unsupported value is rejected with 400 invalid_api_version rather than falling back silently. The version actually served is echoed as X-Mesh-Version on every response, including errors.

Available options:

2026-08

Response

The edited image(s).

Overview

Endpoints

Edit an image

Authorizations

Headers

Response