Retouch4me Cloud AI Retouching API

curl --location 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/start' \
  --form 'file=@"DSC_6229_Sample.jpg"' \
  --form 'token="retoexampletokenvaluex83n4j2k9q7m5p1"' \
  --form-string 'payload={"mode":"professional","tasks":[{"Plugin":"Heal","Scale":0,"Alpha1":1.0},{"Plugin":"Fabric","Scale":0,"Alpha1":0.39},{"Plugin":"Eye Vessels","Scale":0,"Alpha1":1.0},{"Plugin":"Eye Brilliance","Scale":0,"Alpha1":0.5},{"Plugin":"White Teeth","Scale":0,"Alpha1":0.25,"Alpha2":0.25},{"Plugin":"Dodge Burn","Scale":2,"Alpha1":1.0,"Alpha2":0.2},{"Plugin":"Skin Tone","Scale":0,"Alpha1":1.0,"Alpha2":1.0},{"Plugin":"Portrait Volumes","Scale":0,"Alpha1":0.5}]}'

curl --location "https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/start" --form "file=@DSC_6229_Sample.jpg" --form "token=retoexampletokenvaluex83n4j2k9q7m5p1" --form-string "payload={\"mode\":\"professional\",\"tasks\":[{\"Plugin\":\"Heal\",\"Scale\":0,\"Alpha1\":1.0},{\"Plugin\":\"Fabric\",\"Scale\":0,\"Alpha1\":0.39},{\"Plugin\":\"Eye Vessels\",\"Scale\":0,\"Alpha1\":1.0},{\"Plugin\":\"Eye Brilliance\",\"Scale\":0,\"Alpha1\":0.5},{\"Plugin\":\"White Teeth\",\"Scale\":0,\"Alpha1\":0.25,\"Alpha2\":0.25},{\"Plugin\":\"Dodge Burn\",\"Scale\":2,\"Alpha1\":1.0,\"Alpha2\":0.2},{\"Plugin\":\"Skin Tone\",\"Scale\":0,\"Alpha1\":1.0,\"Alpha2\":1.0},{\"Plugin\":\"Portrait Volumes\",\"Scale\":0,\"Alpha1\":0.5}]}"

curl --location 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/getFile/jpeg-example-job-id' \
  --output DSC_6229_Cloud_Retouch.jpg

curl --location "https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/getFile/jpeg-example-job-id" --output DSC_6229_Cloud_Retouch.jpg

Runtime: PHP with cURL enabled.

Download PHP example

<?php
declare(strict_types=1);

const API_BASE = 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher';

$token = getenv('RETOUCH_TOKEN') ?: '<your_token_here>';
$sourceFile = __DIR__ . '/../DSC_6229_Sample.jpg';
$outputFile = __DIR__ . '/../retouch_result_php.jpg';

$payload = [
    'mode' => 'professional',
    'tasks' => [
        ['Plugin' => 'Heal', 'Scale' => 0, 'Alpha1' => 1.0],
        ['Plugin' => 'Fabric', 'Scale' => 0, 'Alpha1' => 0.39],
        ['Plugin' => 'Eye Vessels', 'Scale' => 0, 'Alpha1' => 1.0],
        ['Plugin' => 'Eye Brilliance', 'Scale' => 0, 'Alpha1' => 0.5],
        ['Plugin' => 'White Teeth', 'Scale' => 0, 'Alpha1' => 0.25, 'Alpha2' => 0.25],
        ['Plugin' => 'Dodge Burn', 'Scale' => 2, 'Alpha1' => 1.0, 'Alpha2' => 0.2],
        ['Plugin' => 'Skin Tone', 'Scale' => 0, 'Alpha1' => 1.0, 'Alpha2' => 1.0],
        ['Plugin' => 'Portrait Volumes', 'Scale' => 0, 'Alpha1' => 0.5],
    ],
];

$jobId = startJob($token, $sourceFile, $payload);
$status = waitForCompletion($jobId);
downloadResult($jobId, $outputFile);

function startJob(string $token, string $sourceFile, array $payload): string
{
    $response = requestJson(
        API_BASE . '/start',
        [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => [
                'file' => new CURLFile($sourceFile),
                'token' => $token,
                'payload' => json_encode($payload, JSON_UNESCAPED_SLASHES),
            ],
        ]
    );

    return (string) $response['id'];
}

function waitForCompletion(string $jobId): array
{
    while (true) {
        $response = requestJson(API_BASE . '/status/' . rawurlencode($jobId));

        if (($response['state'] ?? '') === 'completed') {
            return $response;
        }

        if (($response['state'] ?? '') === 'failed') {
            throw new RuntimeException('Job failed: ' . ($response['reason'] ?? 'unknown'));
        }

        sleep(5);
    }
}

function downloadResult(string $jobId, string $outputFile): void
{
    $fp = fopen($outputFile, 'wb');
    $ch = curl_init(API_BASE . '/getFile/' . rawurlencode($jobId));
    curl_setopt_array($ch, [CURLOPT_FILE => $fp, CURLOPT_FOLLOWLOCATION => true]);
    curl_exec($ch);
    curl_close($ch);
    fclose($fp);
}

function requestJson(string $url, array $extraOptions = []): array
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true] + $extraOptions);
    $body = curl_exec($ch);
    curl_close($ch);
    return json_decode((string) $body, true);
}

Runtime: Python 3 standard library only.

Download Python example

import json
import mimetypes
import os
import time
import urllib.request
import uuid

API_BASE = "https://retoucher.hz.labs.retouch4.me/api/v1/retoucher"
SOURCE_FILE = os.path.join(os.path.dirname(__file__), "..", "DSC_6229_Sample.jpg")
OUTPUT_FILE = os.path.join(os.path.dirname(__file__), "..", "retouch_result_python.jpg")
TOKEN = os.environ.get("RETOUCH_TOKEN", "<your_token_here>")

PAYLOAD = {
    "mode": "professional",
    "tasks": [
        {"Plugin": "Heal", "Scale": 0, "Alpha1": 1.0},
        {"Plugin": "Fabric", "Scale": 0, "Alpha1": 0.39},
        {"Plugin": "Eye Vessels", "Scale": 0, "Alpha1": 1.0},
        {"Plugin": "Eye Brilliance", "Scale": 0, "Alpha1": 0.5},
        {"Plugin": "White Teeth", "Scale": 0, "Alpha1": 0.25, "Alpha2": 0.25},
        {"Plugin": "Dodge Burn", "Scale": 2, "Alpha1": 1.0, "Alpha2": 0.2},
        {"Plugin": "Skin Tone", "Scale": 0, "Alpha1": 1.0, "Alpha2": 1.0},
        {"Plugin": "Portrait Volumes", "Scale": 0, "Alpha1": 0.5},
    ],
}

def start_job():
    boundary = f"----RetouchBoundary{uuid.uuid4().hex}"
    body = build_multipart_body(
        boundary,
        [("token", TOKEN), ("payload", json.dumps(PAYLOAD, separators=(",", ":")))],
        [("file", SOURCE_FILE)],
    )
    request = urllib.request.Request(
        f"{API_BASE}/start",
        data=body,
        method="POST",
        headers={"Content-Type": f"multipart/form-data; boundary={boundary}"},
    )
    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))["id"]

def wait_for_completion(job_id):
    while True:
        with urllib.request.urlopen(f"{API_BASE}/status/{job_id}") as response:
            data = json.loads(response.read().decode("utf-8"))
        if data.get("state") == "completed":
            return
        if data.get("state") == "failed":
            raise RuntimeError(data.get("reason", "unknown"))
        time.sleep(5)

def download_result(job_id):
    with urllib.request.urlopen(f"{API_BASE}/getFile/{job_id}") as response:
        with open(OUTPUT_FILE, "wb") as f:
            f.write(response.read())

def build_multipart_body(boundary, fields, files):
    chunks = []
    for name, value in fields:
        chunks += [
            f"--{boundary}\r\n".encode(),
            f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode(),
            str(value).encode(),
            b"\r\n",
        ]
    for field_name, file_path in files:
        filename = os.path.basename(file_path)
        content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
        with open(file_path, "rb") as f:
            file_content = f.read()
        chunks += [
            f"--{boundary}\r\n".encode(),
            f'Content-Disposition: form-data; name="{field_name}"; filename="{filename}"\r\n'.encode(),
            f"Content-Type: {content_type}\r\n\r\n".encode(),
            file_content,
            b"\r\n",
        ]
    chunks.append(f"--{boundary}--\r\n".encode())
    return b"".join(chunks)

job_id = start_job()
wait_for_completion(job_id)
download_result(job_id)

Runtime: Node.js 18+ with native fetch, FormData, and Blob.

Download JavaScript example

const fs = require('node:fs/promises');
const path = require('node:path');

const API_BASE = 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher';
const sourceFile = path.join(__dirname, '..', 'DSC_6229_Sample.jpg');
const outputFile = path.join(__dirname, '..', 'retouch_result_js.jpg');
const token = process.env.RETOUCH_TOKEN || '<your_token_here>';

const payload = {
  mode: 'professional',
  tasks: [
    { Plugin: 'Heal', Scale: 0, Alpha1: 1.0 },
    { Plugin: 'Fabric', Scale: 0, Alpha1: 0.39 },
    { Plugin: 'Eye Vessels', Scale: 0, Alpha1: 1.0 },
    { Plugin: 'Eye Brilliance', Scale: 0, Alpha1: 0.5 },
    { Plugin: 'White Teeth', Scale: 0, Alpha1: 0.25, Alpha2: 0.25 },
    { Plugin: 'Dodge Burn', Scale: 2, Alpha1: 1.0, Alpha2: 0.2 },
    { Plugin: 'Skin Tone', Scale: 0, Alpha1: 1.0, Alpha2: 1.0 },
    { Plugin: 'Portrait Volumes', Scale: 0, Alpha1: 0.5 },
  ],
};

async function startJob() {
  const fileBuffer = await fs.readFile(sourceFile);
  const formData = new FormData();
  formData.append('file', new Blob([fileBuffer]), path.basename(sourceFile));
  formData.append('token', token);
  formData.append('payload', JSON.stringify(payload));

  const response = await fetch(`${API_BASE}/start`, { method: 'POST', body: formData });
  const data = await response.json();
  if (!response.ok) throw new Error(JSON.stringify(data));
  return data.id;
}

async function waitForCompletion(jobId) {
  while (true) {
    const response = await fetch(`${API_BASE}/status/${encodeURIComponent(jobId)}`);
    const data = await response.json();
    if (data.state === 'completed') return;
    if (data.state === 'failed') throw new Error(data.reason || 'unknown');
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

async function downloadResult(jobId) {
  const response = await fetch(`${API_BASE}/getFile/${encodeURIComponent(jobId)}`);
  const buffer = Buffer.from(await response.arrayBuffer());
  await fs.writeFile(outputFile, buffer);
}

(async () => {
  const jobId = await startJob();
  await waitForCompletion(jobId);
  await downloadResult(jobId);
})();

curl --location 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/start' \
  --form 'file=@"DSC_6229_Sample.jpg"' \
  --form 'token="retoexampletokenvaluex83n4j2k9q7m5p1"' \
  --form-string 'payload={"mode":"professional","tasks":[{"Plugin":"Skin Mask","Scale":0,"Alpha1":1.0,"Layer":1},{"Plugin":"Heal","Scale":0,"Alpha1":1.0,"Layer":1},{"Plugin":"Fabric","Scale":0,"Alpha1":0.39,"Layer":1},{"Plugin":"Eye Vessels","Scale":0,"Alpha1":1.0,"Layer":1},{"Plugin":"Eye Brilliance","Scale":0,"Alpha1":0.5,"Layer":1},{"Plugin":"White Teeth","Scale":0,"Alpha1":0.25,"Alpha2":0.25,"Layer":1},{"Plugin":"Dodge Burn","Scale":2,"Alpha1":1.0,"Alpha2":0.2,"Layer":1},{"Plugin":"Skin Tone","Scale":0,"Alpha1":1.0,"Alpha2":1.0,"Layer":1},{"Plugin":"Portrait Volumes","Scale":0,"Alpha1":0.5,"Layer":1}]}'

curl --location "https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/start" --form "file=@DSC_6229_Sample.jpg" --form "token=retoexampletokenvaluex83n4j2k9q7m5p1" --form-string "payload={\"mode\":\"professional\",\"tasks\":[{\"Plugin\":\"Skin Mask\",\"Scale\":0,\"Alpha1\":1.0,\"Layer\":1},{\"Plugin\":\"Heal\",\"Scale\":0,\"Alpha1\":1.0,\"Layer\":1},{\"Plugin\":\"Fabric\",\"Scale\":0,\"Alpha1\":0.39,\"Layer\":1},{\"Plugin\":\"Eye Vessels\",\"Scale\":0,\"Alpha1\":1.0,\"Layer\":1},{\"Plugin\":\"Eye Brilliance\",\"Scale\":0,\"Alpha1\":0.5,\"Layer\":1},{\"Plugin\":\"White Teeth\",\"Scale\":0,\"Alpha1\":0.25,\"Alpha2\":0.25,\"Layer\":1},{\"Plugin\":\"Dodge Burn\",\"Scale\":2,\"Alpha1\":1.0,\"Alpha2\":0.2,\"Layer\":1},{\"Plugin\":\"Skin Tone\",\"Scale\":0,\"Alpha1\":1.0,\"Alpha2\":1.0,\"Layer\":1},{\"Plugin\":\"Portrait Volumes\",\"Scale\":0,\"Alpha1\":0.5,\"Layer\":1}]}"

curl --location 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/getFile/layers-example-job-id' \
  --output DSC_6229_Cloud_Retouch_Layers.zip

curl --location "https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/getFile/layers-example-job-id" --output DSC_6229_Cloud_Retouch_Layers.zip