Car Image API

Клиенты · Студии оклейки, тонировки и антигравийной защиты

Как показать оклейку, тонировку или антигравийную плёнку (PPF) именно на автомобиле клиента

Как мастерские по оклейке, тонировке и защитной плёнке используют белые базовые рендеры, точные hex-цвета и 3D-модели, чтобы показать результат на автомобиле клиента ещё до начала работ.

Руководство для тюнинга и детейлинга

Проблема: клиент хочет увидеть результат на своём автомобиле

Студия оклейки, тонировки или установки защитной плёнки продаёт то, что клиент не может увидеть, пока работа не выполнена. В портфолио — чужие машины. Образец производителя показывает материал на плоской карточке. Продажу закрывает собственный M4 2021 года клиента именно в том сатиновом сером цвете, в котором он сомневается, — а такой фотографии не существует, потому что работа ещё не сделана.

Тот же пробел проявляется и дальше по цепочке. Раскройщику плёнки нужен чистый контур переднего бампера для модельного года, которого ещё нет в библиотеке лекал. Конфигуратору нужно вращающееся изображение автомобиля в базовом цвете, поверх которого дизайнер сможет нанести свою окраску. Всем троим нужно одно и то же: студийное изображение конкретной марки, модели и года в выбранном ими цвете и без какого-либо фона.

Три способа использования рендеров в мастерских

Интеграции для оклейки, тонировки и защитной плёнки, уже работающие с API, решают три задачи, иногда все три сразу:

  • Белая основа, а поверх — материал. Отрендерите модельный год клиента в color=white на прозрачном PNG и наложите на него плёнку, тонировку или печатный дизайн прямо в браузере. Альфа-канал PNG — это контур автомобиля.
  • Цвет по hex-коду. Для однотонной оклейки плёнкой или перекраски обойдитесь без наложения слоёв: color=686c70 возвращает автомобиль уже в этом цвете, не затрагивая стёкла и колёса, как одно изображение автомобиля — так же, как пресет.
  • 3D-модель для вращающегося просмотра. POST /api/v1/3d создаёт текстурированные GLB, USDZ и FBX автомобиля в выбранном цвете — один раз для каждого автомобиля и цвета. К опубликованной модели прилагается код встраивания из двух строк для страницы с расчётом стоимости и USDZ, который клиент может открыть в AR на iPhone.

Одна мастерская запускает свои пакеты через коннектор ChatGPT, а не через код, — это четвёртый сценарий, которому ниже посвящён отдельный раздел.

Белый базовый рендер и материал поверх него

Оклейка заменяет краску, поэтому начинайте с минимума краски. color=white даёт самый светлый нейтральный кузов с сохранённым студийным освещением; прямой вид side показывает максимум боковины при минимальных перспективных искажениях — именно это нужно для предпросмотра материала. Запрашивайте png (или webp), чтобы сохранился альфа-канал, и максимальный размер, 1024, чтобы предпросмотр можно было увеличивать.

Базовый рендер и тот же автомобиль в цвете по hex-коду
# the customer's exact model year, in white: the base every material goes on top of
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_0ta0ejj0qad2w&view=side&color=white&w=1024&format=png" \
  -o m4-side-white.png

# a solid-color wrap or a factory paint, by hex: the API recolors the paint and leaves glass, trim and wheels alone
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_0ta0ejj0qad2w&view=side&color=686c70&w=1024&format=png" \
  -o m4-side-nardo.png

Для текстурного материала наложение — это несколько строк кода на canvas: рендер рисуется один раз как маска, материал наносится только там, где есть автомобиль, а затем рендер рисуется ещё раз в режиме multiply, чтобы светотень и отражения проступили сквозь материал.

Наложение материала на базовый рендер в браузере
// A textured material (carbon, chrome, a printed design) goes on in the browser.
// The white render is the mask: paint the material only where the car is, then let
// the render's own shading through.
const car = await loadImage(whiteBaseUrl); // transparent PNG from the API
const ctx = canvas.getContext("2d");
canvas.width = car.width;
canvas.height = car.height;

ctx.drawImage(car, 0, 0);
ctx.globalCompositeOperation = "source-atop"; // keep the car's alpha
ctx.fillStyle = ctx.createPattern(materialSwatch, "repeat");
ctx.fillRect(0, 0, canvas.width, canvas.height);
ctx.globalCompositeOperation = "multiply"; // shading, reflections and panel lines come back
ctx.drawImage(car, 0, 0);
// The whole silhouette is covered, glass and wheels included: the API ships the car's
// alpha, not per-panel masks. Good enough for a quote; a solid color should use color=<hex> instead.

Подбор цвета краски или плёнки по hex-коду

С тех пор как цвета кузова стали перекраской одного нейтрального рендера, color принимает любой шестизначный hex-код наряду с названиями готовых цветов (15): color=686c70 без решётки в URL, "color": "#686c70" в JSON. Найдите образец цвета производителя или заводской код краски клиента и передайте его. Перекраска применяется только к кузову, поэтому стёкла, фары, отделка и колёса остаются как есть — именно этим превью оклейки отличается от тонированной фотографии. Каждый hex-код — это ещё один кэшируемый вариант и одно изображение автомобиля за месяц, так что палитра из двадцати вариантов для одного автомобиля в одном ракурсе — это двадцать изображений автомобилей.

3D-модель для обзора на 360° и AR

Когда на странице с расчётом стоимости автомобиль должен вращаться, закажите модель. POST /api/v1/3d принимает id автомобиля и цвет, списывает 100 кредитов и создаёт текстурированный GLB, его версию для браузера, USDZ и FBX, а также миниатюру. Первая модель автомобиля создаётся за 10–20 minutes; каждый следующий цвет того же автомобиля перетекстурирует ту же сетку за 1–2 minutes. Повторный заказ автомобиля и цвета, которые у вас уже есть, бесплатен (billing.already_owned: true), поэтому мастерская может строить конфигуратор на одной и той же белой основе для каждого заказа.

Закажите модель в белом цвете и сразу опубликуйте
curl -X POST https://carimage.dev/api/v1/3d \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wrap-quote-4471" \
  -d '{"vehicle": "veh_0ta0ejj0qad2w", "color": "white", "publish": true}'
202 Accepted (фрагмент)
{
  "data": {
    "id": "8c1d6b8e-2b4a-4f6e-9a2e-1f3c5d7e9b01",
    "object": "3d_model",
    "status": "queued",
    "progress": 0,
    "vehicle": {
      "id": "veh_0ta0ejj0qad2w",
      "make": "bmw",
      "model": "m4",
      "year": 2021
    },
    "color": "white",
    "files": null,
    "public": {
      "id": "m3d_…",
      "url": "https://carimage.dev/api/v1/3d/public/m3d_…",
      "files": null,
      "embed": {
        "script": "https://carimage.dev/embed/3d.js",
        "html": "<script src=\"https://carimage.dev/embed/3d.js\" async></script>\n<car-3d model=\"m3d_…\"></car-3d>"
      }
    }
  },
  "billing": {
    "charged_on": "creation",
    "credits_charged": 100,
    "credits_remaining": 24900,
    "already_owned": false
  },
  "request_id": "req_01j9y…"
}

publish: true даёт модели URL без ключа на нашей CDN и код для встраивания ещё до того, как она будет готова; элемент показывает прогресс, пока файлы не загрузятся. Задайте в view любой из девяти ракурсов камеры для начального кадра, spin — для вращения на поворотном столе, backdrop — для студийного пола, а ar — чтобы предложить USDZ для iPhone и GLB для Android через встроенный в браузер AR-просмотрщик. FBX — для дизайнера: откройте его в Blender или в программе для дизайна оклейки, нанесите рисунок на UV-развёртку, и клиент увидит собственный дизайн на собственном автомобиле.

Встраиваемый блок на странице расчёта стоимости
<script src="https://carimage.dev/embed/3d.js" async></script>
<car-3d model="m3d_…" view="front-3-4" spin backdrop="studio" ar alt="2021 BMW M4 in white"></car-3d>

Запуск пакетной обработки из ChatGPT или Claude

Не в каждой мастерской есть разработчик, и одна из самых активных интеграций с API — это оператор, который просит рендеры у ассистента. Добавьте https://carimage.dev/api/mcp как коннектор (ChatGPT и Claude входят через OAuth, а человек подтверждает разрешения на экране), и ассистент получит те же инструменты, что и программа: resolve_vehicle, чтобы превратить «2014 Audi S3 cabriolet, grey, side» в точные параметры, get_car_image для одного рендера, create_car_image_urls для получения до пятидесяти подписанных URL за один вызов и create_3d_model для 3D-модели на поворотном столе.

Чтобы пакетная обработка через ассистента прошла гладко, важны две вещи:

  • Передавайте idempotency_key для каждого пакета. Ассистенты повторяют запросы. С ключом повторный вызов create_car_image_urls воспроизводит первый результат (idempotent_replayed: true) и ничего не списывает.
  • Учитывайте бюджет рендеринга, а не только ограничение частоты запросов. Ракурсы автомобилей, которые ещё никто не запрашивал, сначала нужно подготовить, и на это расходуется дневная доля мощностей подготовки вашего аккаунта (10% на Pro). Партия из нескольких сотен новых автомобилей в трёх ракурсах может её исчерпать; тогда инструмент ответит временем повтора и reset_at, плата не взимается, а кэшированные изображения продолжают выдаваться. Растяните партию на вечер-другой или перейдите на Business, чтобы получить большую долю.

Настройка для каждого клиента и полный список инструментов — на странице MCP.

CLI, SDK и MCP

npx @meterapp/car-image
# the white base and a hex paint, straight to files
npx @meterapp/car-image get --vehicle veh_0ta0ejj0qad2w --view side --color white --width 1024 --out m4-side-white.png
npx @meterapp/car-image get --vehicle veh_0ta0ejj0qad2w --view side --color 686c70 --width 1024 --out m4-side-nardo.png

# the 3D model: published at once, polled until ready, every file downloaded
npx @meterapp/car-image 3d create --vehicle veh_0ta0ejj0qad2w --color white --publish --wait --out ./models
С помощью TypeScript SDK
import { CarImageClient } from "@meterapp/car-image-sdk";

const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });

// 100 credits the first time. Ordering the same vehicle in the same color again
// answers billing.already_owned: true and charges nothing.
const { data: model } = await client.create3dModel({ vehicle: "veh_0ta0ejj0qad2w" }, { color: "white", publish: true });
const ready = await client.wait3dModel(model.id, { onProgress: (m) => console.log(m.stage, m.progress) });

// FBX for the designer's tool of choice, USDZ for the customer's iPhone, glb_web for the page.
const fbx = await client.download3dModel(ready.id, "fbx");
const embedHtml = ready.public?.embed.html;
  • MCP: get_car_image и create_car_image_urls в основном наборе инструментов, create_3d_model, get_3d_model и publish_3d_model — с ?toolset=all; каждый инструмент для изображений принимает vehicle и hex-значение color.
  • Документация по 3D описывает webhooks (один подписанный POST, когда модель готова), размеры файлов и все атрибуты встраивания; раздел Цвета на странице «Изображения» описывает правила окраски.

Часто задаваемые вопросы

Стоит ли произвольный цвет в HEX дороже готового?
Нет. Каждый цвет — это перекраска одного подготовленного ракурса этого автомобиля, поэтому пресет, найденный вами заводской код и образец цвета производителя плёнки засчитываются как одно изображение автомобиля. Hex-код, совпадающий с образцом пресета, и есть этот пресет.
Достаточно ли точен рендер, чтобы по нему кроить плёнку?
Нет. Рендеры — это студийные визуализации марки, модели и года, а не данные CAD и не фотографии производителя: каталог не различает комплектации, а линии панелей могут отличаться на двух видах одного и того же автомобиля. Используйте их, чтобы показать клиенту его автомобиль и рассчитать стоимость работ; лекала для раскроя делайте по шаблону или по самому автомобилю.
Можно ли получить автомобиль без краски или только стёкла?
Ближе всего к заготовке — color=white на прозрачном PNG, а альфа-канал PNG — это силуэт автомобиля. API не предоставляет маски для отдельных панелей или стёкол. Для однотонной оклейки поручите работу color=<hex>: он перекрашивает кузов, оставляя стёкла, декоративные элементы и колёса без изменений.
Какие ракурсы использовать для расчёта тонировки или защитной плёнки?
Прямые ракурсы: side (или side-right) — для боковых стёкол и боковин, front — для полосы на лобовом стекле, капота и бампера, rear — для заднего стекла. Лучше всего клиенты реагируют на ракурсы в три четверти, поэтому используйте front-3-4 для главного изображения, а прямые ракурсы — рядом с позициями сметы.
Принадлежит ли нам 3D-модель?
Она лицензируется так же, как рендеры: оплачивается один раз за каждый автомобиль и цвет в рамках аккаунта, повторный заказ бесплатен, её можно использовать в вашем продукте и хранить на своих серверах, в том числе после окончания тарифа. Каждый следующий цвет уже имеющегося у вас автомобиля накладывает новую текстуру на ту же сетку, а публикация бесплатно даёт модели URL без ключа и код для встраивания.