HTTP API для обработки фото

Мастер API-ключ без списания кредитов

Для внутренних серверных интеграций можно задать MASTER_API_KEY в .env. Такой ключ проходит проверку API без списания кредитов. Используйте его только на backend-стороне: не вставляйте в frontend, мобильные приложения и публичные репозитории.

MASTER_API_KEY=mk_long_random_secret

Мастер-ключ не хранит webhook по умолчанию через /api/v1/webhook. Если нужен webhook для задачи, передавайте webhook_url прямо в /api/v1/process.

/api/v1/process

Ставит фото в очередь обработки и сразу возвращает job_id. Результат можно получить polling-запросом или через webhook. Стоимость успешной задачи: 5 кредитов.

В финальном ответе обработки приходит блок analysis: тип фото, ракурс автомобиля и найденные классы модели.

/api/v1/analyze

Быстрый анализ фото без замены фона и без создания результата. Метод определяет, что на фото: интерьер, экстерьер, подиум, а для экстерьера дополнительно возвращает ракурс автомобиля. Стоимость фиксированная: 1 кредит за успешный запрос.

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

{
  "result": true,
  "code": 200,
  "cost_credits": 1,
  "analysis": {
    "photo_type": {
      "value": "exterior",
      "label": "Экстерьер",
      "source_class": "car-front",
      "conf": 92
    },
    "view": {
      "value": "front",
      "label": "Спереди",
      "source_class": "car-front",
      "conf": 92
    },
    "detections": {
      "car": {"id": 0, "conf": 96},
      "license-plate": {"id": 2, "conf": 88}
    },
    "background_detections": {
      "car-front": {"id": 2, "conf": 92}
    }
  }
}

Очередь, polling и webhook

После создания задачи API вернет статус queued. Проверяйте готовность через GET /api/v1/jobs/{job_id} или укажите webhook в ключе/запросе.

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

Webhook получает такой же JSON, как polling endpoint. Заголовок X-AutoMask-Job содержит ID задачи.

/api/v1/webhook

Позволяет посмотреть, задать, изменить или отключить webhook по умолчанию для текущего API-ключа. Этот URL будет использоваться для всех новых задач, если в /api/v1/process не передан разовый webhook_url.

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

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\"}"

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

{
  "result": true,
  "code": 200,
  "message": "Webhook сохранен",
  "webhook_url": "https://automask.ru/webhooks/automask",
  "webhook_enabled": true
}

Фон, привязанный к API-ключу

В личном кабинете можно сгенерировать отдельный API-ключ и привязать к нему фон по умолчанию: пресет или свой файл. После этого в запросе достаточно передать mode=studio_background. Если background_file не передан, API автоматически возьмет фон, сохраненный у ключа.

curl -X POST https://automask.ru/api/v1/process \
  -H "X-API-Key: KEY_WITH_DEFAULT_BACKGROUND" \
  -F "mode=studio_background" \
  -F "file=@car.jpg"

Если в запросе передать background_file, он имеет приоритет над фоном, сохраненным у ключа.

Для API-ключа также можно сохранить цвет плашки, режим сглаживания и отдельный флаг plate_mask_only. Разовые параметры в запросе переопределят настройку ключа.

Примеры запросов

curl -X POST https://automask.ru/api/v1/process \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@car.jpg" \
  -F "plate_color=#111111" \
  -F "plate_smoothing=true" \
  -F "plate_mask_only=false"

curl -X POST https://automask.ru/api/v1/process \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "mode=studio_background" \
  -F "background=graphite" \
  -F "plate_color=graphite" \
  -F "plate_smoothing=raw" \
  -F "plate_mask_only=true" \
  -F "file=@car.jpg"

curl -X POST https://automask.ru/api/v1/process \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "mode=studio_background" \
  -F "background_file=@my-background.png" \
  -F "file=@car.jpg"

Пример на Python

import requests

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

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

payload = response.json()
job_id = payload["job_id"]

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

if job.get("result"):
    print("Готово:", BASE_URL + job["url"])
    print("Маска:", BASE_URL + job["mask_url"])
else:
    print("Ошибка:", job.get("code"), job.get("message"))

Проверка баланса

quota = requests.get(
    f"{BASE_URL}/api/v1/quota",
    headers={"X-API-Key": API_KEY},
    timeout=30,
).json()

print(quota["quota"]["credits_remaining"])

Webhook по умолчанию

webhook = requests.put(
    f"{BASE_URL}/api/v1/webhook",
    headers={"X-API-Key": API_KEY},
    json={"webhook_url": "https://automask.ru/webhooks/automask"},
    timeout=30,
).json()

print(webhook["webhook_enabled"], webhook["webhook_url"])

Пример на PHP

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

$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" => "showroom",
        "plate_color" => "#111111",
        "plate_smoothing" => "true",
        "plate_mask_only" => "false",
        "file" => new CURLFile(__DIR__ . "/car.jpg"),
    ],
]);

$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
curl_close($ch);

$payload = json_decode($response, true);
$jobId = $payload["job_id"];

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

if (!empty($job["result"])) {
    echo "Готово: " . $baseUrl . $job["url"] . PHP_EOL;
    echo "Маска: " . $baseUrl . $job["mask_url"] . PHP_EOL;
} else {
    echo "Ошибка {$job["code"]}: {$job["message"]}" . PHP_EOL;
}

Проверка баланса

<?php
$ch = curl_init($baseUrl . "/api/v1/quota");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . $apiKey],
]);

$quota = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Кредиты: " . $quota["quota"]["credits_remaining"] . PHP_EOL;

Webhook по умолчанию

<?php
$ch = curl_init($baseUrl . "/api/v1/webhook");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: " . $apiKey,
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "webhook_url" => "https://automask.ru/webhooks/automask",
    ], JSON_UNESCAPED_SLASHES),
]);

$webhook = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Webhook: " . ($webhook["webhook_enabled"] ? $webhook["webhook_url"] : "выключен") . PHP_EOL;

Ответ при создании задачи

{
  "result": true,
  "queued": true,
  "code": 202,
  "message": "Задача поставлена в очередь.",
  "cost_credits": 5,
  "job_id": "job_abc123",
  "status": "queued",
  "status_url": "/api/v1/jobs/job_abc123",
  "webhook_enabled": true,
  "quota": {
    "remaining": 45,
    "credits_remaining": 45,
    "process_credit_cost": 5,
    "classification_credit_cost": 1
  }
}

Финальный ответ задачи

{
  "result": true,
  "job_id": "job_abc123",
  "status": "success",
  "code": 200,
  "url": "/results/result.webp",
  "plate_mask_url": "/masks/result_mask_lp.png",
  "background_mask_url": "/masks/result_mask_bg.png",
  "mask_url": "/masks/result_mask_bg.png",
  "expires_in_days": 7,
  "mode": "studio_background",
  "background": "custom",
  "plate_color": "#111111",
  "plate_smoothing": true,
  "plate_mask_only": false,
  "analysis": {
    "photo_type": {"value": "exterior", "label": "Экстерьер", "conf": 97},
    "view": {"value": "three_quarters_left", "label": "Три четверти слева", "conf": 97}
  },
  "quota": {
    "remaining": 40,
    "credits_remaining": 40
  }
}

/api/v1/quota

Возвращает баланс API-ключа: текущий остаток кредитов, общий расход и статус доступа. Дневных лимитов в модели нет.

curl "https://automask.ru/api/v1/quota?api_key=YOUR_API_KEY"

{
  "result": true,
  "quota": {
    "active": true,
    "authorized": true,
    "remaining": 50,
    "credits_remaining": 50,
    "user_credits_remaining": 50,
    "process_credit_cost": 5,
    "classification_credit_cost": 1,
    "used_total": 0
  }
}

Коды ошибок