Může render zůstat zveřejněný i poté, co dorazí fotografie aukční položky?

Nahraďte ho. Render je zástupný obrázek modelového roku a dražitel by nikdy neměl váhat, který obrázek je prodávané auto. Pokud ho stránka ponechá pro srovnání, popisek zůstává u něj.

Co se stane s URL po skončení aukce?

Platnost vyprší po uplynutí nastavené doby, u obnovovaných URL na konci období obnovování, a poté odkaz vrací 403. V té době už má položka vlastní fotografie nebo výsledek a archiv aukce by měl zobrazovat fotografie. Zrušením klíče, kterým byly URL vygenerovány, skončí platnost všech najednou.

Opakovaný požadavek vrátil 422. Proč?

Stejný Idempotency-Key přišel s jiným tělem požadavku. Obvyklou příčinou je doba platnosti přepočítaná podle hodin v okamžiku opakování. Dobu platnosti stanovte při vytvoření položky a uložte ji; opakovaný požadavek pak odešle stejné tělo a vrátí znovu první odpověď.

Může render zobrazit lak dané položky?

Ano: color přijímá libovolný z přednastavených názvů nebo hex, takže obrázek může bez příplatku odpovídat laku z konsignačního listu. Pořád je to ale model v tomto laku, ne konkrétní položka aukce, takže označení zůstává.

Kolik stojí aukce s 400 položkami?

400 obrázků vozidel z měsíčního limitu: 1 obrázek vozidla za aukční položku při vygenerování její URL, přičemž opakované vygenerování se znovu nepočítá. Každé načtení během platnosti URL je zdarma. Tarify zahrnují měsíčně Free 100, Pro 2 500 a Business 10 000 obrázků vozidel a položky se stejným vozidlem, lakem a pohledem se počítají jednou.

Obrázky aut pro aukční nabídky

Průvodce implementací vycházející ze zdokumentovaného chování API; nejmenuje žádného zákazníka. Publikováno 30. září 2026.

Problém: aukce běží dřív, než jsou hotové fotky

Aukční katalog se zveřejní, jakmile jsou přijaty všechny konsignace: u každého vozu VIN, číslo položky a datum aukce. Fotografie přijdou, až vůz dorazí na parkoviště a fotograf k vozu, což je u části aukce až po zahájení přihazování. Do té doby je každá z těchto položek jen šedým rámečkem vedle řádku textu.

Katalogový render vyplní rámeček správným modelovým rokem. Aukce je ale zároveň přesně tím místem, kde se render nikdy nesmí vydávat za skutečné auto: dražitelé oceňují stav a render žádný neukazuje, protože nezobrazuje žádné konkrétní fyzické vozidlo. Vše níže vychází z toho, že platí obojí současně.

Jak integrace vypadá

Render pro každou položku podle jejího VIN, zobrazený jen do doby, než dorazí vlastní fotky položky.
Výběr z katalogu pro položky, jejichž VIN nelze dekódovat.
Popisek na obrázku: „Katalogový render, nejde o tuto položku“.
Jedna URL na aukční položku, vygenerovaná jednou pod Idempotency-Key, platná po celou dobu aukce.

Krok 1: od VIN položky k ID vozidla

GET /api/v1/vin/{vin} je zdarma. Pokud katalog vozidlo obsahuje, odpověď vrátí data.vehicle.id, stabilní ID, které uložíte k položce; dekódovaná výbava, karoserie a motor zůstávají v textu položky. Katalog pokrývá roky 1990 až 2027, takže starší vozy v aukci se vykreslí stejně jako ty nejnovější. Návod pro pojišťovnictví prochází dekódování pole po poli a dokumentace k VIN popisuje částečné VIN a chyby.

Dekódování při příjmu

# the lot's VIN to the vehicle id the lot stores (free); nothing printed means no catalog match
npx @meterapp/car-image vin "$LOT_VIN" --json | jq -r '.data.vehicle.id // empty'

Krok 2: VIN nelze dekódovat? Vyberte vozidlo z katalogu

Některé položky přicházejí bez VIN, který lze dekódovat: vozidlo vyrobené pro jiný trh, VIN, který zdroj zadal chybně, nebo konsignační list jen s rokem, značkou a modelem. Dejte formuláři pro konsignaci tři rozbalovací nabídky napájené z GET /api/v1/vehicles, které je zdarma a veřejné: ?year= vypíše značky, které mají v daném roce nějaký model, a ?year=&makeId= vypíše modely dané značky, každý s id vozidla pro daný modelový rok.

Rok, pak značka, pak model

# every make with a 2006 model year (free, public)
curl -s "https://carimage.dev/api/v1/vehicles?year=2006"
# {"data":{"year":2006,"makes":[…,{"id":476,"name":"DODGE","slug":"dodge"},…]},…}

# that make's 2006 models, each with the id of its 2006 model year
curl -s "https://carimage.dev/api/v1/vehicles?year=2006&makeId=476"

200 OK (zkráceno)

{
  "data": {
    "year": 2006,
    "make_id": 476,
    "models": [
      {
        "name": "Caliber",
        "slug": "caliber",
        "vehicle_type": "Passenger Car",
        "id": "veh_294vq81yq0d3y"
      },
      {
        "name": "Charger",
        "slug": "charger",
        "vehicle_type": "Passenger Car",
        "id": "veh_96j8z47jqfd4r"
      },
      "…"
    ]
  }
}

Stejný katalog tvoří otevřený balíček @meterapp/vehicle-db, takže rozbalovací nabídky mohou běžet i offline nad identickým seznamem. V obou případech položka nakonec uchovává stejný druh id jako dekódovaný VIN a nic dál v procesu nepracuje s textovým názvem auta.

Když dorazí celý soupis aukčních položek najednou, POST /api/v1/vehicles/check přečte až 2 000 záznamů na jedno volání, každý tak, jak je zapsán v soupisu, a s číslem položky jako ref, a odpoví na každý z nich: shoda s id k uložení, návrhy, nenalezeno nebo neplatný řádek. Nic se nerenderuje a nic se neúčtuje; podrobnosti najdete v dokumentaci k vozidlům.

Krok 3: označte render jako render

Označení umístěte přímo na obrázek, kam padne zrak dražitele, a do alternativního textu, nejen do popisu pod ním. Stav, najeté kilometry, poškození, výbava a lak vozu patří do textu aukční položky a – jakmile budou k dispozici – na fotografie. Jakmile dorazí fotografie, render zmizí.

Obrázek položky, dokud nedorazí její fotografie

<figure class="lot-image">
  <img src="https://carimage.dev/api/v1/delivery/eyJhbGciOi…" width="800" height="450"
       alt="Catalog render of a 2006 Dodge Charger, not a photo of lot 117">
  <span class="lot-image__badge">Catalog render, not this lot</span>
</figure>
<p>Photos of this lot are on their way. Condition, mileage and damage are in the report.</p>

Render se nikdy nesmí vydávat za skutečnou položku

Render ukazuje značku, model a rok z katalogu ve studiu a může chybovat v detailech výbavy, emblémech a kolech (přesnost obrázků). Podmínky také zakazují zkreslovat, kdo obrázek vytvořil nebo jak. Viditelný popisek udrží inzerát poctivý a dražitele informovaného.

Krok 4: jedna URL pro každou položku, vygenerovaná jednou

Vygenerujte URL položky při příjmu pomocí POST /api/v1/image-urls a Idempotency-Key složeného z aukce a položky, z písmen, číslic a znaků ., _, : a -. URL započítá svůj obrázek jako obrázek vozidla daného měsíce v okamžiku vygenerování, takže bez klíče by opakovaný příjem vygeneroval druhou URL. S klíčem:

Stejný klíč se stejným tělem požadavku do 24 hodin zopakuje první odpověď včetně stejné URL, s hlavičkou Idempotent-Replayed: true a bez druhého účtování.
Stejný klíč s jiným tělem vrátí 422 a opakovaný požadavek, který předběhne ten první, vrátí 409 s hlavičkou Retry-After. Proto vše v těle požadavku, včetně doby platnosti, zafixujte už při vytvoření aukční položky a uložte to spolu s ní.
Uložte URL i k položce: klíč chrání opakované pokusy a uloženou URL čtou stránky po zbytek aukce.

Celý katalog importovaný najednou může vytvořit až 50 aukčních položek na jedno volání, s klíčem pro každou dávku; každá URL v odpovědi uvádí vozidlo a možnosti, pro které byla vytvořena.

URL položky 117

curl --fail-with-body -X POST https://carimage.dev/api/v1/image-urls \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sale-2026-10-14:lot-117" \
  -d '{"images":[{"vehicle":"veh_96j8z47jqfd4r","view":"side","width":800,"height":450,"fit":"contain","trim":true,"padding":6,"format":"auto"}],"ttl_seconds":259200}'
# run it again: the same URL comes back with Idempotent-Replayed: true, and nothing more is charged

Krok 5: přizpůsobte dobu platnosti URL délce aukce

ttl_seconds může být až 604800 (7 dní); delší hodnota se na tento limit zkrátí. U aukce, která končí do týdne, nastavte čas zbývající do jejího konce. Zástupný obrázek pak přestane fungovat ve chvíli, kdy skončí přihazování, a poté URL vrací 403.

Časově omezený prodej delší než 7 dní: vystavte URL s renew: true, ttl_seconds na maximu a renew_days pokrývajícím dobu prodeje. Obnovení započítá obrázek jednou v měsíci, kdy proběhne, a nic dalšího, pokud už byl v daném měsíci započítán; týdny, kdy položku nikdo neotevře, se nezapočítají vůbec a obnovování skončí v renews_until.
Ponechte max_uses na 0, což je výchozí hodnota: neomezenou URL lze po celou dobu její platnosti veřejně ukládat do mezipaměti, zatímco omezená má private, no-store a každé načtení posílá na zdrojový server.
Omezte klíč, kterým generujete URL, na domény vaší aukce v ovládacím panelu: obrázek položky zkopírovaný na jiný web vrátí 403.

Příjem položek s TypeScript SDK

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

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

const lotImage = (vehicle: string): ImageParams => ({
  vehicle, view: "side", width: 800, height: 450, fit: "contain", trim: true, padding: 6, format: "auto",
});

// How long the lot's URL lives, decided once from the sale's close.
function lifetime(closesAt: Date) {
  const seconds = secondsUntil(closesAt);
  return seconds <= 604800
    ? { ttlSeconds: Math.max(seconds, 60) } // closes within the week
    : { ttlSeconds: 604800, renew: true, renewDays: Math.min(daysUntil(closesAt), 365) }; // a longer timed sale
}

// At intake, once per lot. The lifetime is stored with the lot, so a retry sends
// the same body and replays the first answer instead of minting a second URL.
lot.imageLifetime ??= lifetime(sale.closesAt);
const { data: [placeholder] } = await client.createImageUrls(lotImage(lot.vehicleId), {
  ...lot.imageLifetime,
  idempotencyKey: `${sale.id}:lot-${lot.number}`,
});
lot.placeholderUrl = placeholder.url; // replaced by the lot's own photos when they arrive

Zvolte tarif podle velikosti aukce

Každá položka je jeden obrázek vozidla, tedy její vozidlo v daném laku a pohledu, pokud se dvě položky neshodují ve všech třech, a každý tarif zahrnuje určitý počet obrázků vozidel měsíčně: Free 100, Pro 2 500 a Business 10 000; Enterprise se sjednává individuálně. Obrázek, který už byl tento měsíc započítán, se zobrazí vždy, a dávka, která by překročila limit, se odmítne celá, ještě než se cokoli započítá, a odpověď uvede tarif a limit. Tarif zvolte podle počtu položek, které za měsíc vystavíte. Případová studie tržiště popisuje, jak rozložit velký import v rámci limitů požadavků a vykreslování.

Často kladené otázky

Může render zůstat zveřejněný i poté, co dorazí fotografie aukční položky?: Nahraďte ho. Render je zástupný obrázek modelového roku a dražitel by nikdy neměl váhat, který obrázek je prodávané auto. Pokud ho stránka ponechá pro srovnání, popisek zůstává u něj.
Co se stane s URL po skončení aukce?: Platnost vyprší po uplynutí nastavené doby, u obnovovaných URL na konci období obnovování, a poté odkaz vrací 403. V té době už má položka vlastní fotografie nebo výsledek a archiv aukce by měl zobrazovat fotografie. Zrušením klíče, kterým byly URL vygenerovány, skončí platnost všech najednou.
Opakovaný požadavek vrátil 422. Proč?: Stejný Idempotency-Key přišel s jiným tělem požadavku. Obvyklou příčinou je doba platnosti přepočítaná podle hodin v okamžiku opakování. Dobu platnosti stanovte při vytvoření položky a uložte ji; opakovaný požadavek pak odešle stejné tělo a vrátí znovu první odpověď.
Může render zobrazit lak dané položky?: Ano: color přijímá libovolný z přednastavených názvů nebo hex, takže obrázek může bez příplatku odpovídat laku z konsignačního listu. Pořád je to ale model v tomto laku, ne konkrétní položka aukce, takže označení zůstává.
Kolik stojí aukce s 400 položkami?: 400 obrázků vozidel z měsíčního limitu: 1 obrázek vozidla za aukční položku při vygenerování její URL, přičemž opakované vygenerování se znovu nepočítá. Každé načtení během platnosti URL je zdarma. Tarify zahrnují měsíčně Free 100, Pro 2 500 a Business 10 000 obrázků vozidel a položky se stejným vozidlem, lakem a pohledem se počítají jednou.

Čtěte dál

Příběh zákazníka · Automobilová tržištěJak přidat ke každému inzerátu na tržišti studiový obrázek autaInzerát potřebuje obrázek dříve, než ho prodejce nahraje. Tržiště doplní celý katalog jedním úhlem a jedním lakem a pak u každého nového modelového roku zachovají stejnou podobu požadavku.