> For the complete documentation index, see [llms.txt](https://docs.jgscripts.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jgscripts.com/vehicle-studio/api.md).

# API

JG Vehicle Studio has two exports for getting vehicle image URLs from other scripts.

These exports work on **both** client and server.

```lua
exports["jg-vehiclestudio"]:getImage(...)
exports["jg-vehiclestudio"]:getImages(...)
```

### getImage

Returns the stored image URL for a vehicle and an ordered list of computed fallback image URLs.

```lua
---@param spawnCode string|number
---@param imageId? string Defaults to "default"
---@return string|nil image
---@return string[] fallbacks
local image, fallbacks = exports["jg-vehiclestudio"]:getImage(spawnCode, imageId)
```

**Return values**

* `image`: The stored Vehicle Studio image URL for the requested vehicle and image set. This is `nil` when Vehicle Studio does not have a saved image for that vehicle/image set.
* `fallbacks`: Ordered fallback image URLs with `{MODEL}`, `{model}`, `{HASH}` and `{hash}` tokens resolved for the requested vehicle.

Fallback URLs are returned as candidates only. The export does not check whether remote fallback images exist. Browser/NUI integrations should try the returned URLs in order and use the first one that loads.

When a fallback URL has no variable tokens, it is treated as a final static fallback. Any configured fallbacks after that static URL are not returned.

**Example**

```lua
local image, fallbacks = exports["jg-vehiclestudio"]:getImage("adder")
```

### getImages

Returns stored image URLs and computed fallback image URLs for multiple vehicles.

```lua
---@param spawnCodes string[]|number[]
---@param imageId? string Defaults to "default"
---@return table<string|number, { image: string|nil, fallbacks: string[] }>
local images = exports["jg-vehiclestudio"]:getImages(spawnCodes, imageId)
```

Each entry in the returned table contains:

* `image`: The stored Vehicle Studio image URL for that vehicle, or `nil`.
* `fallbacks`: Ordered computed fallback image URLs for that vehicle.

**Example**

```lua
local images = exports["jg-vehiclestudio"]:getImages({
  "adder",
  "zentorno",
  "t20",
})
```

**Example result**

```lua
{
  adder = {
    image = "https://images.example.com/jg-vehiclestudio/image/adder.webp?v=1710000000",
    fallbacks = {
      "https://docs.fivem.net/vehicles/adder.webp",
      "https://cfx-nui-jg-vehiclestudio/web/dist/no-vehicle-image.png",
    },
  },
  zentorno = {
    image = nil,
    fallbacks = {
      "https://docs.fivem.net/vehicles/zentorno.webp",
      "https://cfx-nui-jg-vehiclestudio/web/dist/no-vehicle-image.png",
    },
  },
}
```

### Image IDs

`imageId` is the image set ID.

If you do not pass an `imageId`, Vehicle Studio uses `"default"`.

```lua
local defaultImage = exports["jg-vehiclestudio"]:getImage("adder")
local orangeImage = exports["jg-vehiclestudio"]:getImage("adder", "orange_bg")
```

Use the same image ID you selected when photographing the vehicle in Vehicle Studio.

### Browser/NUI fallback handling

NUI integrations should try the primary `image` first, then each fallback URL in order. Use the first URL that successfully loads.

```ts
interface VehicleImageCandidates {
  image?: string | null;
  fallbacks?: string[];
}

const imageProbeCache = new Map<string, boolean>();

function probeImage(url: string): Promise<boolean> {
  const cached = imageProbeCache.get(url);
  if (cached !== undefined) return Promise.resolve(cached);

  return new Promise((resolve) => {
    const img = new Image();

    img.onload = () => {
      imageProbeCache.set(url, true);
      resolve(true);
    };

    img.onerror = () => {
      imageProbeCache.set(url, false);
      resolve(false);
    };

    img.src = url;
  });
}

export async function resolveVehicleImage(
  candidates: VehicleImageCandidates,
): Promise<string | null> {
  const urls = [candidates.image, ...(candidates.fallbacks ?? [])].filter(
    (url): url is string => typeof url === "string" && url.length > 0,
  );

  for (const url of urls) {
    if (await probeImage(url)) return url;
  }

  return null;
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.jgscripts.com/vehicle-studio/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.