# Image Upload API

Upload images with AI-generated or manual captions for multimodal search.

## Overview

Images are indexed with both:
- **Visual embeddings** (Nova Multimodal) - find visually similar images
- **Text embeddings** (captions) - find images by description

## Dashboard Image Tab

The Image Upload tab provides:

### Caption Prompt Editor
Customize the AI prompt used to generate image captions. Changes apply immediately to new uploads.

**Location:** Image Upload tab → Caption Prompt (expandable section)

**Default prompt:** Generates concise, searchable captions focusing on main subject, setting, and visual elements.

## Single Image Upload (Auto-Process)

For the simplest workflow, use `autoProcess: true` to let AI generate captions automatically:

```graphql
mutation CreateImageUploadUrl($filename: String!, $autoProcess: Boolean, $userCaption: String) {
  createImageUploadUrl(filename: $filename, autoProcess: $autoProcess, userCaption: $userCaption) {
    uploadUrl    # Presigned S3 POST URL
    imageId      # Unique identifier for this upload
    s3Uri        # S3 URI for the image
    fields       # Form fields for S3 POST (JSON string)
  }
}
```

**Parameters:**
- `filename` (required): Original filename with extension
- `autoProcess`: Set to `true` for automatic AI caption generation after upload
- `userCaption`: Optional user-provided caption (combined with AI caption if autoProcess=true)

With `autoProcess: true`, just upload the file and processing happens automatically via EventBridge.

### Auto-Process JavaScript Example

```javascript
async function uploadImageAutoProcess(imageFile, userCaption = '') {
  // 1. Get presigned URL with autoProcess enabled
  const urlRes = await fetch(ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({
      query: `mutation($filename: String!, $autoProcess: Boolean!, $userCaption: String) {
        createImageUploadUrl(filename: $filename, autoProcess: $autoProcess, userCaption: $userCaption) {
          uploadUrl, imageId, fields
        }
      }`,
      variables: { filename: imageFile.name, autoProcess: true, userCaption: userCaption }
    })
  });
  const { uploadUrl, imageId, fields } = (await urlRes.json()).data.createImageUploadUrl;

  // 2. Upload to S3 - processing starts automatically
  const form = new FormData();
  Object.entries(JSON.parse(fields)).forEach(([k, v]) => form.append(k, v));
  form.append('file', imageFile);
  await fetch(uploadUrl, { method: 'POST', body: form });

  return imageId;  // Image will be processed and indexed automatically
}
```

## Single Image Upload (Manual Steps)

For more control, use the 4-step process:

### Step 1: Get Upload URL

```graphql
mutation CreateImageUploadUrl($filename: String!) {
  createImageUploadUrl(filename: $filename) {
    uploadUrl    # Presigned S3 POST URL
    imageId      # Unique identifier for this upload
    s3Uri        # S3 URI for caption generation
    fields       # Form fields for S3 POST (JSON string)
  }
}
```

### Step 2: Upload to S3

```javascript
const form = new FormData();
Object.entries(JSON.parse(fields)).forEach(([k, v]) => form.append(k, v));
form.append('file', imageFile);
await fetch(uploadUrl, { method: 'POST', body: form });
```

### Step 3: Generate AI Caption (Optional)

Use Bedrock vision models to generate a descriptive caption:

```graphql
mutation GenerateCaption($imageS3Uri: String!) {
  generateCaption(imageS3Uri: $imageS3Uri) {
    caption      # AI-generated description
  }
}
```

The caption is optimized for search with relevant keywords.

### Step 4: Submit Image

Finalize the upload with caption(s) to trigger processing:

```graphql
mutation SubmitImage($input: SubmitImageInput!) {
  submitImage(input: $input) {
    imageId
    filename
    status       # PROCESSING → INDEXED
  }
}

# Input
{
  "input": {
    "imageId": "abc123",
    "userCaption": "My manual description",  # Optional
    "aiCaption": "AI-generated description"  # Optional
  }
}
```

If both captions provided, they're combined: `"{userCaption}. {aiCaption}"`

## Complete JavaScript Example

```javascript
const ENDPOINT = 'https://your-api.appsync-api.region.amazonaws.com/graphql';
const API_KEY = 'your-api-key';

async function uploadImageWithCaption(imageFile) {
  // 1. Get presigned URL
  const urlRes = await fetch(ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({
      query: `mutation($filename: String!) {
        createImageUploadUrl(filename: $filename) {
          uploadUrl, imageId, s3Uri, fields
        }
      }`,
      variables: { filename: imageFile.name }
    })
  });
  const { uploadUrl, imageId, s3Uri, fields } = (await urlRes.json()).data.createImageUploadUrl;

  // 2. Upload to S3
  const form = new FormData();
  Object.entries(JSON.parse(fields)).forEach(([k, v]) => form.append(k, v));
  form.append('file', imageFile);
  await fetch(uploadUrl, { method: 'POST', body: form });

  // 3. Generate AI caption
  const captionRes = await fetch(ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({
      query: `mutation($imageS3Uri: String!) {
        generateCaption(imageS3Uri: $imageS3Uri) { caption }
      }`,
      variables: { imageS3Uri: s3Uri }
    })
  });
  const aiCaption = (await captionRes.json()).data.generateCaption.caption;

  // 4. Submit with caption
  await fetch(ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({
      query: `mutation($input: SubmitImageInput!) {
        submitImage(input: $input) { imageId, status }
      }`,
      variables: { input: { imageId, aiCaption } }
    })
  });

  return imageId;
}
```

## Batch Upload (ZIP Archive)

Upload multiple images at once with optional automatic caption generation.

### Create ZIP Upload URL

```graphql
mutation CreateZipUploadUrl($generateCaptions: Boolean) {
  createZipUploadUrl(generateCaptions: $generateCaptions) {
    uploadUrl
    uploadId
    fields
  }
}
```

Set `generateCaptions: true` to auto-generate AI captions for images without manual captions.

### ZIP File Structure

```
images.zip
├── photo1.jpg
├── photo2.png
├── subfolder/
│   └── photo3.gif
└── captions.json    # Optional manifest
```

### captions.json Format

Provide manual captions for specific images:

```json
{
  "photo1.jpg": "Sunset over the mountains with golden clouds",
  "photo2.png": "City skyline at night with lights reflecting on water",
  "subfolder/photo3.gif": "Animated loading spinner"
}
```

Images not in the manifest will get AI-generated captions if `generateCaptions=true`.

### JavaScript Example

```javascript
async function uploadImageZip(zipFile, generateCaptions = true) {
  // 1. Get presigned URL
  const res = await fetch(ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({
      query: `mutation($generateCaptions: Boolean) {
        createZipUploadUrl(generateCaptions: $generateCaptions) {
          uploadUrl, uploadId, fields
        }
      }`,
      variables: { generateCaptions }
    })
  });
  const { uploadUrl, uploadId, fields } = (await res.json()).data.createZipUploadUrl;

  // 2. Upload ZIP to S3
  const form = new FormData();
  Object.entries(JSON.parse(fields)).forEach(([k, v]) => form.append(k, v));
  form.append('file', zipFile);
  await fetch(uploadUrl, { method: 'POST', body: form });

  // Processing happens automatically via EventBridge
  return uploadId;
}
```

## Supported Formats

- **Images:** JPG, JPEG, PNG, GIF, WebP, AVIF
- **Max size:** 50 MB per image, 500 MB per ZIP

## Querying Images

After indexing, images are searchable via:

```graphql
query SearchKnowledgeBase($query: String!) {
  searchKnowledgeBase(query: $query) {
    results {
      content      # Caption text
      s3Uri        # Image location
      score        # Relevance score
    }
  }
}
```

Both text queries ("sunset mountains") and image similarity work through the unified Bedrock KB.

## Authentication

All mutations require either:
- **API Key:** `x-api-key` header
- **Cognito:** JWT token in `Authorization` header

Get your API key from the Settings page in the web UI.