Image Sizes Guide

Each Mars photo is available in multiple sizes for different use cases.

Important: Size Availability Varies by Rover

Perseverance: All 4 sizes (small, medium, large, full)
Curiosity, Spirit, Opportunity: Only full (NASA provides one URL per photo)

Always use full as your fallback size.

Available Sizes

The API provides up to 4 image sizes, depending on the rover:

Size	Max Width	Typical File Size	Availability	Best For
small	320px	~10-30 KB	Perseverance only	Thumbnails, lists
medium	800px	~50-150 KB	Perseverance only	Previews, galleries
large	1200px	~100-300 KB	Perseverance only	Full-screen views
full	Original	~200 KB - 2 MB	All rovers	Downloads, analysis

Response Format

Image URLs are returned in the images object:

Perseverance (All 4 Sizes)

{
  "data": [{
    "attributes": {
      "images": {
        "small": "https://mars.nasa.gov/..._320.jpg",
        "medium": "https://mars.nasa.gov/..._800.jpg",
        "large": "https://mars.nasa.gov/..._1200.jpg",
        "full": "https://mars.nasa.gov/..._full.jpg"
      }
    }
  }]
}

Curiosity, Spirit, Opportunity (Full Only)

{
  "data": [{
    "attributes": {
      "images": {
        "small": null,
        "medium": null,
        "large": null,
        "full": "https://mars.nasa.gov/msl-raw-images/.../1000MR0044631340603692E01_DXXX.jpg"
      }
    }
  }]
}

Note on Legacy Field

The img_src field is deprecated and returns an empty string. Always use the images object instead.

When to Use Each Size

smallThumbnails & Lists

Use for thumbnail grids, search results, and mobile lists. Loads quickly and saves bandwidth.

// React example: Thumbnail grid
{photos.map(photo => (
  <img
    src={photo.attributes.images.small}
    alt={`Sol ${photo.attributes.sol}`}
    className="w-20 h-20 object-cover"
  />
))}

mediumGalleries & Previews

Best for photo galleries, card layouts, and preview images. Good balance of quality and size.

// React example: Gallery card
<div className="max-w-md">
  <img
    src={photo.attributes.images.medium}
    alt={`Sol ${photo.attributes.sol}`}
    className="w-full rounded-lg"
  />
</div>

largeFull-Screen & Detail Views

Use for lightboxes, modal views, and desktop full-width displays. High quality without huge file sizes.

// React example: Lightbox view
<dialog className="fixed inset-0 bg-black">
  <img
    src={photo.attributes.images.large}
    alt={`Sol ${photo.attributes.sol}`}
    className="max-w-full max-h-full object-contain"
  />
</dialog>

fullDownloads & Analysis

Original NASA image. Use for downloads, scientific analysis, or printing. Can be very large.

// Download button
<a
  href={photo.attributes.images.full}
  download={`mars-${photo.id}.jpg`}
>
  Download Full Resolution
</a>

Progressive Loading Pattern

For the best user experience, implement progressive loading. Always fall back to full when smaller sizes are unavailable:

// React progressive loading with fallback
function MarsPhoto({ photo }) {
  const { images } = photo.attributes;

  // Always use full as fallback (available for all rovers)
  const initialSrc = images.small ?? images.full;
  const targetSrc = images.large ?? images.full;

  const [src, setSrc] = useState(initialSrc);
  const [loaded, setLoaded] = useState(false);

  useEffect(() => {
    if (targetSrc && targetSrc !== src) {
      const img = new Image();
      img.src = targetSrc;
      img.onload = () => {
        setSrc(targetSrc);
        setLoaded(true);
      };
    }
  }, [photo, targetSrc, src]);

  return (
    <img
      src={src}
      className={`transition-opacity ${loaded ? 'opacity-100' : 'opacity-70'}`}
      alt={`Mars photo from Sol ${photo.attributes.sol}`}
    />
  );
}

Requesting Specific Sizes

To reduce response size, you can request only the image sizes you need:

# Only small and medium images
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.marsvista.dev/api/v2/photos?image_sizes=small,medium"

# Metadata only (no images)
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.marsvista.dev/api/v2/photos?exclude_images=true"

Image Dimensions

Each photo includes dimension information in the dimensions object:

{
  "attributes": {
    "dimensions": {
      "width": 1920,
      "height": 1080
    },
    "aspect_ratio": 1.78  // computed: width / height
  }
}

You can filter by dimensions:

# High resolution only (1920x1080+)
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.marsvista.dev/api/v2/photos?min_width=1920&min_height=1080"

# Widescreen photos only
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.marsvista.dev/api/v2/photos?aspect_ratio_min=1.5&aspect_ratio_max=2.0"

Sample Types

NASA categorizes images by their sample type. Filter to get only the quality you need:

Type	Description
Full	Full resolution image
Subframe	Cropped region of interest
Thumbnail	Low-res preview (often grayscale)

# Full quality images only
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.marsvista.dev/api/v2/photos?sample_type=Full"

Next Steps

Filtering & Pagination →Learn advanced query techniques
Photos Reference →All photo query parameters