Image Edit

Get API Key

The Image Edit API applies AI-powered edits to one or multiple reference images that you host. Provide the edit prompt, the target model, and optional aspect-ratio hints to steer the results.

API Overview

• Request URL: https://www.cutout.pro/api/v1/image/edit
• Method: POST
• Content-Type: application/json
• Headers:
  • APIKEY: Your API key from the user center

Sample Code

curl

curl --location --request POST 'https://www.cutout.pro/api/v1/image/edit' \
  --header 'APIKEY: INSERT_YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "prompt": "Describe the edit you want",
    "model": "model-name",
    "aspectRatios": "16:9",
    "imageUrl": [
      "https://example.com/source.jpg"
    ]
  }'

python

import requests

payload = {
    "prompt": "Describe the edit you want",
    "model": "model-name",
    "aspectRatios": "16:9",
    "imageUrl": [
        "https://example.com/source.jpg"
    ]
}

response = requests.post(
    "https://www.cutout.pro/api/v1/image/edit",
    json=payload,
    headers={
        "APIKEY": "INSERT_YOUR_API_KEY_HERE",
        "Content-Type": "application/json"
    }
)
response.raise_for_status()
print(response.json())

php

$client = new GuzzleHttp\Client();

$response = $client->post('https://www.cutout.pro/api/v1/image/edit', [
    'headers' => [
        'APIKEY' => 'INSERT_YOUR_API_KEY_HERE',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'prompt' => 'Describe the edit you want',
        'model' => 'model-name',
        'aspectRatios' => '16:9',
        'imageUrl' => [
            'https://example.com/source.jpg'
        ]
    ]
]);

echo $response->getBody();

java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

var client = HttpClient.newHttpClient();
var body = """
{
  "prompt": "Describe the edit you want",
  "model": "model-name",
  "aspectRatios": "16:9",
  "imageUrl": [
    "https://example.com/source.jpg"
  ]
}
""";

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.cutout.pro/api/v1/image/edit"))
    .header("APIKEY", "INSERT_YOUR_API_KEY_HERE")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

nodejs

const payload = {
  prompt: "Describe the edit you want",
  model: "model-name",
  aspectRatios: "16:9",
  imageUrl: [
    "https://example.com/source.jpg"
  ]
};

async function makeRequest() {
  try {
    const response = await fetch("https://www.cutout.pro/api/v1/image/edit", {
      method: "POST",
      headers: {
        APIKEY: "INSERT_YOUR_API_KEY_HERE",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });

    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error:', error);
  }
}

makeRequest();

.net

using var client = new HttpClient();

var requestBody = new
{
    prompt = "Describe the edit you want",
    model = "model-name",
    aspectRatios = "16:9",
    imageUrl = new[] { "https://example.com/source.jpg" }
};

var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://www.cutout.pro/api/v1/image/edit")
{
    Content = new StringContent(
        System.Text.Json.JsonSerializer.Serialize(requestBody),
        System.Text.Encoding.UTF8,
        "application/json")
};

request.Headers.Add("APIKEY", "INSERT_YOUR_API_KEY_HERE");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

objective-c

NSDictionary *payload = @{
    @"prompt": @"Describe the edit you want",
    @"model": @"model-name",
    @"aspectRatios": @"16:9",
    @"imageUrl": @[@"https://example.com/source.jpg"]
};

NSError *error = nil;
NSData *body = [NSJSONSerialization dataWithJSONObject:payload options:0 error:&error];
if (error) { return; }

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://www.cutout.pro/api/v1/image/edit"]];
request.HTTPMethod = @"POST";
request.HTTPBody = body;
[request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
[request setValue:@"INSERT_YOUR_API_KEY_HERE" forHTTPHeaderField:@"APIKEY"];

NSURLSessionDataTask *task = [[NSURLSession sharedSession]
    dataTaskWithRequest:request
    completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
        if (error) { return; }
        NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
        NSLog(@"%@", json);
}];
[task resume];

Request Parameters

Headers

Parameter	Type	Required	Description
APIKEY	string	Yes	Your Cutout.Pro API key

JSON Body

Field	Type	Required	Description
prompt	string	Yes	Natural language description of the desired edit
model	string	Yes	Image-editing model identifier to use
aspectRatios	string	Yes	Preferred aspect ratio hint such as 1:1, 4:3, 16:9, etc.
imageUrl	array<string>	Yes	List the HTTPS URLs for the source images to be edited. The images must be in JPEG or PNG format and accessible via HTTPS

Model-specific Requirements

Model	pricePerCall (credits)	Max imageUrl refs	Allowed aspectRatios	Additional constraints
gpt-image-1	4	≤ 6 images	original, 1:1, 4:3, 3:4, 9:16, 16:9	None
gemini-2.5-flash-image	4	≤ 6 images	original, 1:1, 4:3, 3:4, 9:16, 16:9	None
gemini-3-pro-image-preview	15	≤ 6 images	original, 1:1, 4:3, 3:4, 9:16, 16:9	None
seedream-4.0	4	≤ 6 images	original, 1:1, 4:3, 3:4, 9:16, 16:9	size ≤ 10 MB; pixels ≥ 921,600; max 6000×6000 px; width and height > 14 px; aspect ratio between 1/3 and 3.
qwen-image-edit-plus	4	≤ 3 images	original, 1:1, 4:3, 3:4, 9:16, 16:9	None

Response

{
  "code": 0,
  "data": {
    "id": 789012345678901,
    "userId": 657890123456789,
    "imageUrl": "https://cdn.cutout.pro/edits/{result}.jpg",
    "prompt": "Remove the background",
    "model": "qwen-image-edit-plus",
    "aspectRatios": "original",
    "referenceImageUrl": [
      "https://cdn.cutout.pro/upload/{source-1}.jpg"
    ],
    "status": 1,
    "failReason": null,
    "deleted": 0,
    "duration": "11.43",
    "createdAt": 1763547221159
  },
  "msg": "",
  "time": 1763547234171,
  "requestId": "691d9854b3289731e75d37936de5be50"
}

Field	Description
code	Standard API status code (0 = success).
id	Unique identifier of the edit task.
userId	Account that initiated the job.
imageUrl	Final edited image URL returned by the service.
prompt	Prompt text used for the edit.
model	Model name that processed the request.
aspectRatios	The ratio that was applied to the output.
referenceImageUrl	Array of reference image URLs provided in the request.
status	1 indicates the edit finished successfully, 0 indicates failure.
failReason	Error message when status = 0; null when successful.
deleted	Soft-delete flag for internal lifecycle management.
duration	Time spent generating the result, in seconds.
createdAt	Task creation timestamp (milliseconds since epoch).
msg	Optional message for the overall API call.
time	Timestamp when the response was generated.
requestId	Trace identifier for debugging and support.

Error Handling

On failure the service returns JSON with an error code and message:

{
  "code": 1001,
  "data": null,
  "msg": "Insufficient balance",
  "time": 1716273912000
}

Refer to docs/error-code.md for the full list of error codes.