Why we are changing image delivery

Until now, device endpoints could include large base64-encoded images directly inside the JSON response. This worked, but it made responses heavy and slower to transfer, especially when listing or syncing many devices at once. To fix this, MobileAPI.dev is moving to a model where JSON responses return small thumbnails while full-resolution images are fetched separately through dedicated endpoints.

Thumbnails in device responses

The device list and detail endpoints (such as /devices and /devices/{id}) will now return a 100x100 thumbnail instead of the full image in main_image_b64. The field name stays the same, but its contents are much smaller, which reduces payload sizes from hundreds of kilobytes to just a few kilobytes per device. At the same time, the images array is removed from these responses, so devices are focused on core specs plus a tiny preview image.

For most list and search views, this thumbnail is all you need to show a quick device preview. When a user opens a detail page or zooms into a gallery, that is when you call the dedicated image endpoints to load the full-resolution assets.

Listing images with /devices/{id}/images/

Instead of embedding full images in every device payload, the new approach uses a dedicated images listing endpoint. You can call /devices/{id}/images/ to get structured metadata for each image, including fields like id, image_url, caption, is_official, and order. This endpoint no longer returns base64 data. It gives you clean metadata and URLs so you can decide when and how to load large assets.

A typical response looks like this:

[
  {
    "id": 123,
    "image_url": "/images/123/",
    "caption": "Front view",
    "is_official": true,
    "order": 0
  },
  {
    "id": 120,
    "image_url": "/images/120/",
    "caption": "International model",
    "is_official": true,
    "order": 1
  }
]

In your frontend or backend, you can use image_url directly as the source for image tags, CDNs, or media proxies. This keeps your API responses small while still giving you full control over how images are rendered and cached.

Serving full-resolution images and credit usage

Full-resolution images are now served through two dedicated endpoints: /images/{id}/ for gallery images and /devices/{id}/image/ for the main device image. When you call these endpoints, the API checks your key, deducts one image credit, and returns the binary image data with the correct content type (PNG or JPEG). If the request is unauthorized you get a 401 response, and if your image credits are exhausted you receive a 429 response.

This design makes image usage explicit and predictable. You can continue to browse devices using thumbnails at very low cost, and only pay credits when you intentionally retrieve full-resolution images for display or processing.

What you need to change in your integration

If your integration relied on large base64 images in image_b64 or on the images array inside device responses, you will need to update your code. Treat image_b64 as a small thumbnail only, and remove any assumptions that it contains a full-resolution image. Where you previously read images from the device-level images field, switch to calling /devices/{id}/images/ to get the list of images and their URLs.

A common migration path looks like this: first, keep using your existing device endpoints, but only for metadata and thumbnails. Second, after you have a device ID, call /devices/{id}/images/ whenever you need a gallery. Finally, use the image_url field from that response to request full images via /images/{id}/ or use /devices/{id}/image/ for the primary image. This pattern keeps your UI snappy while giving you fine-grained control over when credits are consumed.

Backwards compatibility and timeline

To keep changes manageable, the image_b64 field name remains the same so that existing parsers do not break on missing keys. What changes is the size and role of this field: it is now a 100x100 thumbnail instead of a full-resolution asset. Removing the images array from device responses is a deliberate breaking change, so any code that depends on that array must be updated to use the new /devices/{id}/images/ endpoint. Image access through the new image endpoints will now consume credits, so it is important to review your usage patterns and monitoring.

If you have questions or need help with your migration, contact support with example requests and responses from your current integration. The team can suggest the minimal code changes needed and help you verify that thumbnails, image lists, and credit consumption are all working as expected.