# Using the CardSight AI API - Card Image API

## Overview
Retrieve card images from the CardSight AI catalog. Returns either raw binary image data or a base64-encoded data URI depending on the format requested.

## Endpoint Details
- **Method**: GET
- **URL**: `https://api.cardsight.ai/v1/images/cards/{id}`
- **Authentication**: API Key required (X-Api-Key header)

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | UUID | Yes | The card UUID (path parameter) |
| format | string | No | Response format: `raw` (default) returns binary JPEG, `json` returns base64 data URI |

## Using the CardSight AI SDK (Recommended)

### Node.js / TypeScript
```typescript
import { CardSightAI } from 'cardsightai'

const client = new CardSightAI({ apiKey: 'your-api-key' })

// Get image as JSON with base64 data URI
const response = await client.images.cards('550e8400-e29b-41d4-a716-446655440000', {
  format: 'json'
})

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  console.log('Content Type:', response.data.contentType)
  console.log('Size:', response.data.size, 'bytes')

  // Use the data URI directly in an img tag
  // <img src={response.data.data} />
}
```

### Python
```python
from cardsightai import CardSightAI

client = CardSightAI(api_key='your-api-key')

# Get image as JSON with base64 data URI
response = client.images.cards('550e8400-e29b-41d4-a716-446655440000', format='json')

print(f"Content Type: {response.content_type}")
print(f"Size: {response.size} bytes")
# response.data contains the base64 data URI
```

## Direct API Calls (cURL)

```bash
# Get raw binary image (default)
curl -X GET "https://api.cardsight.ai/v1/images/cards/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key" \
  --output card.jpg

# Get image as JSON with base64 data URI
curl -X GET "https://api.cardsight.ai/v1/images/cards/550e8400-e29b-41d4-a716-446655440000?format=json" \
  -H "X-Api-Key: your-api-key"
```

## Response Formats

### Raw Format (default)
When `format=raw` or no format specified, the API returns binary JPEG image data directly.

**Content-Type**: `image/jpeg`

The response body is the raw image bytes, suitable for saving to a file or streaming.

### JSON Format
When `format=json`, the API returns a JSON object with the image as a base64 data URI.

```json
{
  "data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "contentType": "image/jpeg",
  "size": 45678
}
```

## Response Fields (JSON format)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| data | string | Yes | Base64 data URI (ready for use in HTML img src) |
| contentType | string | Yes | MIME type of the image (e.g., "image/jpeg") |
| size | number | No | Size of the image in bytes |

## Common Use Cases
- Display card images in web applications (use JSON format for data URIs)
- Download card images for offline storage (use raw format)
- Show visual previews for card search results
- Build card galleries and collection displays

## Tips for AI Assistants
- **Working with the card `id`:** The card `id` you pass here comes from a catalog, search, or identify call. This endpoint is one of several free endpoints — free precisely because it assumes you already made that catalog call, so you're not double-charged. Caching an image or its `id` briefly to fulfill a user's request is expected and fine. If you need to save cards for the long term, add them to a list or collection; if you need a bulk or offline copy of catalog data, reach out to us at `support@cardsight.ai` to talk through your use case.
- The SDK returns `{ data, error }` - always check for errors first
- Use `format=json` when you need a data URI for direct HTML/CSS use
- Use `format=raw` (default) when downloading or streaming images
- Not all cards have images available - handle 404 responses gracefully
- The data URI from JSON format can be used directly in `<img src="...">` tags
- Images are returned as JPEG format