Показывает ли изображение ту комплектацию, для которой рассчитан платёж?

Нет. Каталог идентифицирует автомобили по марке, модели и году, поэтому все комплектации одного модельного года отображаются как один и тот же автомобиль. Укажите комплектацию в тексте предложения рядом с изображением и никогда не выдавайте изображение за эту комплектацию или за автомобиль в наличии.

Стоит ли заводской цвет дороже пресета?

Нет. Любой цвет — это перекраска одного подготовленного ракурса, поэтому hex учитывается как одно изображение автомобиля, как и любой из 15 готовых цветов, а hex, совпадающий с образцом готового цвета, и есть этот цвет. Hex применяется как точное значение sRGB при студийном освещении, поэтому сравните рендер с образцом цвета до публикации предложения.

Сколько стоит конфигуратор с 4 вариантами окраски?

400 кредитов единоразово: 100 кредитов за каждый цвет окраски автомобиля. Повторный заказ автомобиля и цвета, которые уже есть в вашем аккаунте, бесплатен (billing.already_owned равно true); публикация, опрос статуса, скачивание и каждая загрузка опубликованной модели также бесплатны.

Сколько времени занимает создание 3D-модели и что будет, если оно не удастся?

Первая модель автомобиля создаётся за 10–20 minutes; каждый следующий цвет того же автомобиля использует ту же полигональную сетку и занимает 1–2 minutes. За неудавшуюся модель средства возвращаются полностью, а если 3D-генерация достигла дневного лимита, запрос отклоняется с указанием времени для повтора ещё до какого-либо списания.

Может ли PDF с расчётом сохранить изображение после окончания предложения?

Да. На платном тарифе лицензия распространяется на рендер в материалах, которые ваш продукт создаёт для клиентов, включая коммерческие предложения и брошюры, пока тариф активен; в течение 30 дней после его окончания сохранённые копии удаляются. Изображения, которые должны навсегда остаться в сохранённых предложениях, можно один раз купить в составе Image Pack.

Изображения автомобилей для лизинговых расчётов и предложений

Руководство по интеграции, написанное на основе документированного поведения API; конкретные клиенты в нём не упоминаются. Опубликовано 30 сентября 2026 г..

Проблема: предложение точное, а изображение — нет

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

Затем то же предложение отправляется дальше: на страницу модели, в PDF с расчётом, в email и в конфигуратор, где клиент вращает автомобиль. Везде нужен один и тот же автомобиль в одном и том же цвете.

Как выглядит интеграция

Отдельное предложение для каждого модельного года, с ключом по id автомобиля из каталога для этого года.
Заводской цвет краски в виде hex-кода на каждом изображении предложения.
Одно и то же изображение в PDF с предложением и в письме — через подписанные URL, поэтому ни документ, ни рендерер никогда не хранят ключ.
3D-модель для каждого цвета для конфигуратора, публикуемая в виде двухстрочного кода встраивания.

Шаг 1: привяжите каждое предложение к id автомобиля его модельного года

GET /api/v1/vehicles?make=&model= — бесплатный и публичный метод, который возвращает все годы модели, каждый со стабильным идентификатором автомобиля. Сохраните идентификатор модельного года из предложения вместе с предложением.

Все годы одной модели

curl -s "https://carimage.dev/api/v1/vehicles?make=honda&model=cr-v"

200 OK (сокращено)

{
  "data": {
    "make": {
      "id": 474,
      "name": "HONDA",
      "slug": "honda"
    },
    "model": {
      "name": "CR-V",
      "slug": "cr-v",
      "vehicle_type": "Passenger Car"
    },
    "vehicles": [
      "…",
      {
        "year": 2025,
        "id": "veh_exjyt8r21gmhe"
      },
      {
        "year": 2026,
        "id": "veh_b6kgpb03d73r9"
      },
      {
        "year": 2027,
        "id": "veh_8nr7res56a6jq"
      }
    ]
  }
}

Когда выходят предложения на 2027 год, они получают id 2027 года, а предложения на 2026 год сохраняют свой: id никогда не меняется, поэтому страница или расчёт, построенные на нём, продолжают работать после смены модельного года. Каталог индексируется по марке, модели и году, поэтому комплектация, для которой рассчитан платёж (EX-L, Sport Touring), указывается текстом в предложении и никогда не утверждается изображением.

Шаг 2: заводской цвет кузова по hex-коду

15 готовых цветов покрывают распространённые оттенки; а для предложения нужен тот цвет, в котором автомобиль действительно продаётся. Возьмите hex с образца цвета производителя и передайте его без символа в URL (color=1f3a5f) или с # в JSON ("color": "#1f3a5f"). Hex учитывается так же, как готовый цвет, — одно изображение автомобиля, потому что любой цвет — это перекраска одного подготовленного ракурса, а hex, совпадающий с образцом готового цвета, и есть этот цвет и кешируется один раз.

Изображение для предложения

# the 2026 offer's hero: its model year, in the paint it is offered in, cropped to a 16:9 slot
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_b6kgpb03d73r9&view=front-3-4&color=1f3a5f&w=1024&h=576&fit=contain&trim=1&padding=4&format=webp" \
  -o cr-v-2026-offer.webp

Сверьте рендер с образцом краски

Цвет в формате hex применяется как точное значение sRGB при студийном освещении, но рендер всё равно может ошибиться в цвете или детали (см. точность изображений). Проверьте рендер до публикации предложения, а о неточном рендере сообщите через карточку «Последние изображения» в панели управления.

Шаг 3: PDF с расчётом и email с предложением через подписанные URL

PDF с коммерческим предложением обычно представляет собой HTML, отрисованный PDF-сервисом или headless-браузером. Вставляйте в шаблон подписанный URL из POST /api/v1/image-urls, а не ключ: рендерер загружает изображение один раз и встраивает его, поэтому срока действия по умолчанию в 1 час вполне достаточно, а format: "jpg" накладывает изображение на белый фон, что подходит для документа. URL засчитывает своё изображение как изображение автомобиля за месяц в момент создания.

Письмо с предложением открывают тогда, когда клиент до него доберётся. Создавайте URL для его изображения с renew: true и ttl_seconds с максимальным значением — 7 дн., а в renew_days укажите число дней, оставшихся до конца предложения: продление засчитывает изображение один раз в том месяце, на который оно приходится, и ничего сверх того, если в этом месяце оно уже было засчитано; тихие недели ничего не стоят, а когда предложение заканчивается, URL перестаёт продлеваться и истекает. На платном тарифе лицензия распространяется на рендер в составе того, что ваш продукт создаёт для клиентов, включая коммерческое предложение.

PDF и письмо с помощью TypeScript SDK

import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";

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

// The offer's picture: its model year, in the paint it is offered in.
const offerImage: ImageParams = {
  vehicle: offer.vehicleId, view: "front-3-4", color: offer.paintHex, // "#1f3a5f"
  width: 1024, height: 576, fit: "contain", trim: true, padding: 4,
};

// The quote PDF: rendered from HTML, the picture loaded once and embedded, on white.
const { data: [forPdf] } = await client.createImageUrls({ ...offerImage, format: "jpg" });
const pdf = await renderQuotePdf({ ...quote, vehicleImageUrl: forPdf.url });

// The offer email: loads for as long as the offer runs, then stops renewing.
const { data: [forEmail] } = await client.createImageUrls(
  { ...offerImage, width: 600, height: 338, format: "auto" },
  {
    ttlSeconds: 604800,
    renew: true,
    renewDays: Math.min(Math.max(daysUntil(offer.endsOn), 1), 365),
    idempotencyKey: `offer:${offer.id}:email`,
  }
);

Шаг 4: 3D-модель для конфигуратора

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

Один цвет конфигуратора

curl --fail-with-body -X POST https://carimage.dev/api/v1/3d \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: configurator-cr-v-2026-1f3a5f" \
  -d '{"vehicle": "veh_b6kgpb03d73r9", "color": "#1f3a5f", "publish": true}'

202 Accepted (фрагмент)

{
  "data": {
    "id": "5b0f3c2e-8a41-4d7e-9c10-2f6e1a3b4d58",
    "object": "3d_model",
    "status": "queued",
    "progress": 0,
    "vehicle": {
      "id": "veh_b6kgpb03d73r9",
      "make": "honda",
      "model": "cr-v",
      "year": 2026
    },
    "color": "#1f3a5f",
    "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,
    "already_owned": false
  }
}

Опрашивайте GET /api/v1/3d/{id} (раз в 10–15 секунд вполне достаточно) или передайте webhook_url вместе с webhook_secret и получите один подписанный POST, когда модель будет готова. data.public.embed.html — это скрипт и элемент <car-3d>: вставьте его на страницу предложения. Элемент сразу показывает постер и загружает просмотрщик, когда модель впервые попадает в область видимости; view, spin, backdrop, ar и alt задают начальный ракурс, вращение на поворотном столе, фон, кнопку AR на телефонах (Quick Look через USDZ на iOS) и alt-текст. Публикация и все загрузки бесплатны.

Выбор цвета для опубликованных моделей

<script src="https://carimage.dev/embed/3d.js" async></script>

<select id="paint" aria-label="Paint">
  <option value="1f3a5f">Blue</option>
  <option value="white">White</option>
</select>

<!-- One published model per paint. Only the visible one is loaded: the script
     fetches a viewer the first time a model scrolls into view. -->
<car-3d data-paint="1f3a5f" model="m3d_…" view="front-3-4" spin backdrop="studio" ar
        alt="2026 Honda CR-V in the offer's blue"></car-3d>
<car-3d data-paint="white" model="m3d_…" view="front-3-4" spin backdrop="studio" ar
        alt="2026 Honda CR-V in white" hidden></car-3d>

<script>
  document.querySelector("#paint").addEventListener("change", (event) => {
    for (const model of document.querySelectorAll("car-3d[data-paint]")) {
      model.hidden = model.dataset.paint !== event.target.value;
    }
  });
</script>

Для конфигуратора нужно столько же моделей, сколько в нём цветов (4), — это 400 кредитов один раз. Мастерские по оклейке плёнкой и тонировке, работающие с API, заказывают 3D-модели так же; в их истории описаны файлы и форматы, а в документации по 3D — webhooks, скачивание и снятие с публикации.

CLI, SDK и MCP

CLI: npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --wait заказывает цвет, дожидается его готовности и выводит код для встраивания.
SDK: client.vehicles({ make, model }), client.createImageUrls(…), client.create3dModel({ vehicle }, { color, publish: true }) и client.wait3dModel(id).
MCP: с ?toolset=all инструменты create_3d_model, get_3d_model и publish_3d_model позволяют ассистенту заказать и опубликовать модель в нужном цвете по просьбе менеджера по продажам. Настройка описана на странице MCP.

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

Показывает ли изображение ту комплектацию, для которой рассчитан платёж?: Нет. Каталог идентифицирует автомобили по марке, модели и году, поэтому все комплектации одного модельного года отображаются как один и тот же автомобиль. Укажите комплектацию в тексте предложения рядом с изображением и никогда не выдавайте изображение за эту комплектацию или за автомобиль в наличии.
Стоит ли заводской цвет дороже пресета?: Нет. Любой цвет — это перекраска одного подготовленного ракурса, поэтому hex учитывается как одно изображение автомобиля, как и любой из 15 готовых цветов, а hex, совпадающий с образцом готового цвета, и есть этот цвет. Hex применяется как точное значение sRGB при студийном освещении, поэтому сравните рендер с образцом цвета до публикации предложения.
Сколько стоит конфигуратор с 4 вариантами окраски?: 400 кредитов единоразово: 100 кредитов за каждый цвет окраски автомобиля. Повторный заказ автомобиля и цвета, которые уже есть в вашем аккаунте, бесплатен (billing.already_owned равно true); публикация, опрос статуса, скачивание и каждая загрузка опубликованной модели также бесплатны.
Сколько времени занимает создание 3D-модели и что будет, если оно не удастся?: Первая модель автомобиля создаётся за 10–20 minutes; каждый следующий цвет того же автомобиля использует ту же полигональную сетку и занимает 1–2 minutes. За неудавшуюся модель средства возвращаются полностью, а если 3D-генерация достигла дневного лимита, запрос отклоняется с указанием времени для повтора ещё до какого-либо списания.
Может ли PDF с расчётом сохранить изображение после окончания предложения?: Да. На платном тарифе лицензия распространяется на рендер в материалах, которые ваш продукт создаёт для клиентов, включая коммерческие предложения и брошюры, пока тариф активен; в течение 30 дней после его окончания сохранённые копии удаляются. Изображения, которые должны навсегда остаться в сохранённых предложениях, можно один раз купить в составе Image Pack.