## Purpose

Canonical specification for mcp-image-provider-integration requirements synced from OpenSpec change deltas.

## Requirements

### Requirement: Pixabay image retrieval
The system SHALL support retrieving images from Pixabay API when `PIXABAY_API_KEY` is configured.

#### Scenario: Successful Pixabay image search
- **WHEN** Pixabay is enabled in provider chain AND query is "artificial intelligence breakthrough"
- **THEN** system sends GET request to `https://pixabay.com/api/?key={key}&q=artificial+intelligence+breakthrough&image_type=photo&per_page=3&safesearch=true`
- **AND** returns first hit's `webformatURL` as image URL
- **AND** returns credit as `"Photo by {user} on Pixabay"`

#### Scenario: Pixabay returns no results
- **WHEN** Pixabay search returns empty `hits` array
- **THEN** system returns `(None, None)` for this provider
- **AND** fallback chain continues to next provider

#### Scenario: Pixabay API key not configured
- **WHEN** `PIXABAY_API_KEY` environment variable is empty or unset
- **THEN** Pixabay provider is skipped in the fallback chain

### Requirement: Unsplash image retrieval
The system SHALL support retrieving images from Unsplash API when `UNSPLASH_ACCESS_KEY` is configured.

#### Scenario: Successful Unsplash image search
- **WHEN** Unsplash is enabled in provider chain AND query is "machine learning robot"
- **THEN** system sends GET request to `https://api.unsplash.com/search/photos?query=machine+learning+robot&per_page=3` with header `Authorization: Client-ID {key}`
- **AND** returns first result's `urls.regular` as image URL
- **AND** returns credit as `"Photo by {user.name} on Unsplash"`

#### Scenario: Unsplash returns no results
- **WHEN** Unsplash search returns empty `results` array
- **THEN** system returns `(None, None)` for this provider
- **AND** fallback chain continues to next provider

#### Scenario: Unsplash API key not configured
- **WHEN** `UNSPLASH_ACCESS_KEY` environment variable is empty or unset
- **THEN** Unsplash provider is skipped in the fallback chain

### Requirement: Pexels image retrieval
The system SHALL support retrieving images from Pexels API when `PEXELS_API_KEY` is configured.

#### Scenario: Successful Pexels image search
- **WHEN** Pexels is enabled in provider chain AND query is "tech startup office"
- **THEN** system sends GET request to `https://api.pexels.com/v1/search?query=tech+startup+office&per_page=3` with header `Authorization: {key}`
- **AND** returns first photo's `src.large` as image URL
- **AND** returns credit as `"Photo by {photographer} on Pexels"`

#### Scenario: Pexels returns no results
- **WHEN** Pexels search returns empty `photos` array
- **THEN** system returns `(None, None)` for this provider
- **AND** fallback chain continues to next provider

#### Scenario: Pexels API key not configured
- **WHEN** `PEXELS_API_KEY` environment variable is empty or unset
- **THEN** Pexels provider is skipped in the fallback chain

### Requirement: Provider timeout handling
Each provider API call SHALL timeout after 15 seconds.

#### Scenario: Provider request timeout
- **WHEN** provider API does not respond within 15 seconds
- **THEN** system logs timeout warning
- **AND** returns `(None, None)` for this provider
- **AND** fallback chain continues to next provider

### Requirement: Provider error handling
The system SHALL gracefully handle provider API errors without crashing.

#### Scenario: Provider returns HTTP error
- **WHEN** provider API returns 4xx or 5xx status code
- **THEN** system logs error with status code
- **AND** returns `(None, None)` for this provider
- **AND** fallback chain continues to next provider

#### Scenario: Provider returns malformed response
- **WHEN** provider API returns invalid JSON or unexpected schema
- **THEN** system logs parsing error
- **AND** returns `(None, None)` for this provider
- **AND** fallback chain continues to next provider