Jobs, reusable assets and batch API

POST /api/v1/jobs supports analysis, plate hiding, background replacement with the plate preserved, and mask-only output. Upload once with /api/v1/assets.

List your jobs, cancel or retry them, and manage ZIP batches. The legacy endpoints below remain compatible.

Full guide and examples (Russian) · Download OpenAPI (English)

/api/v1/process

Queues a processing task and immediately returns a job_id. Successful plate hiding or background replacement costs 5 credits.

curl -X POST https://automask.ru/api/v1/process \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: order-123-photo-1" \
  -F "mode=studio_background" \
  -F "background=studio" \
  -F "plate_color=#111111" \
  -F "plate_smoothing=true" \
  -F "plate_mask_only=false" \
  -F "file=@car.jpg"

/api/v1/analyze

Queues classification without editing the photo and returns 202 Accepted with a job_id. Successful classification costs 1 credit.

curl -X POST https://automask.ru/api/v1/analyze \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: catalog-42-analysis" \
  -F "file=@car.jpg"

/api/v1/jobs/{job_id}

Polls the queued task. Status values: queued, processing, success, failed.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://automask.ru/api/v1/jobs/job_123

/api/v1/webhook

Reads, sets or removes the default webhook URL for an API key. A per-task webhook_url sent to /api/v1/process overrides the default URL.

curl -X PUT https://automask.ru/api/v1/webhook \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"webhook_url\":\"https://automask.ru/webhooks/automask\"}"

Default Background And Plate Color

An API key can store a default background and a default license plate fill color. If plate_color is not sent in /api/v1/process, the service uses the key setting. A per-request plate_color overrides the key default.

Webhook Payload

{
  "job_id": "job_123",
  "status": "success",
  "result": true,
  "mode": "studio_background",
  "plate_color": "#111111",
  "plate_smoothing": true,
  "plate_mask_only": false,
  "url": "/results/result.webp",
  "mask_url": "/masks/result_mask_bg.png",
  "analysis": {
    "photo_type": {"value": "exterior", "label": "Exterior", "conf": 97},
    "view": {"value": "three_quarters_left", "label": "Three quarters left", "conf": 97}
  }
}

Python Example

import time
import requests

BASE_URL = "https://automask.ru"
API_KEY = "YOUR_API_KEY"

with open("car.jpg", "rb") as image:
    response = requests.post(
        f"{BASE_URL}/api/v1/process",
        headers={"X-API-Key": API_KEY},
        files={"file": image},
        data={"mode": "studio_background", "background": "studio", "plate_color": "#111111", "plate_smoothing": "true", "plate_mask_only": "false"},
        timeout=60,
    )
response.raise_for_status()
job_id = response.json()["job_id"]

while True:
    status_response = requests.get(
        f"{BASE_URL}/api/v1/jobs/{job_id}",
        headers={"X-API-Key": API_KEY},
        timeout=30,
    )
    payload = status_response.json()
    if payload["status"] in ("success", "failed"):
        print(payload)
        break
    time.sleep(2)

PHP Example

<?php
$baseUrl = "https://automask.ru";
$apiKey = "YOUR_API_KEY";

$ch = curl_init("$baseUrl/api/v1/process");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
    CURLOPT_POSTFIELDS => [
        "mode" => "studio_background",
        "background" => "studio",
        "plate_color" => "#111111",
        "plate_smoothing" => "true",
        "plate_mask_only" => "false",
        "file" => new CURLFile(__DIR__ . "/car.jpg"),
    ],
]);
$payload = json_decode(curl_exec($ch), true);
curl_close($ch);

$jobId = $payload["job_id"];
do {
    sleep(2);
    $statusCh = curl_init("$baseUrl/api/v1/jobs/$jobId");
    curl_setopt_array($statusCh, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
    ]);
    $status = json_decode(curl_exec($statusCh), true);
    curl_close($statusCh);
} while (!in_array($status["status"], ["success", "failed"], true));

print_r($status);
?>

Credits And Errors