Skip to main content

Stock Photos Integration

Connect your Pexels account to give agents access to high-quality stock images. Agents can search Pexels, retrieve a stable hosted URL, and embed photos directly in content such as LinkedIn posts and reports.

Overview​

The Stock Photos Integration connects a single Pexels API key per tenant and creates the find_stock_photo agent tool. When an agent calls the tool, the platform searches Pexels, re-hosts the chosen image in Azure Blob Storage, and returns a stable SAS URL plus attribution metadata so the agent can reference the image in its output.

Default access model:

Agent kindAccess
CAIOODefault ON - enabled automatically when you connect
Personal AssistantsDefault ON - enabled automatically when you connect
SME AgentsGrant-gated - off by default; toggle per agent on the connection page
Mailbox / Standard / Custom AgentsGrant-gated - off by default; toggle per agent on the connection page
info

Stock Photos requires the custom.stock-photos feature on your subscription. Contact your Outermind account manager if this is not included.

Getting Started​

Prerequisites​

  1. A Pexels account with a generated API key (free tier is sufficient for most usage levels).
  2. Admin access to the Outermind Control Bridge console.

Step 1: Open the Connection Page​

  1. Navigate to Capabilities > Connections.
  2. Click Stock Photos (listed under the Media category).

Step 2: Enter Your Pexels API Key​

  1. Click Connect.
  2. Paste your Pexels API key into the API Key field.
  3. Click Test to verify the key before saving. The platform makes a live call to Pexels to confirm the key is valid.
  4. Click Connect to save the connection.

On success, the find_stock_photo tool is created and CAIOO and all Personal Assistants receive access automatically.

tip

Generate your Pexels API key at www.pexels.com/api/new. The key is free and allows up to 200 requests per hour and 20,000 per month on the standard tier.

Step 3: Grant Access to SME and Mailbox Agents (Optional)​

CAIOO and Personal Assistants are enabled by default. To extend access to SME or Mailbox agents:

  1. On the connection page, scroll to the Agent Access section.
  2. Agents with default-on access (CAIOO and PAs) are shown as always-enabled with a lock icon.
  3. For each SME or Mailbox agent listed, toggle Find Stock Photo to ON.
  4. Changes take effect immediately.

Connection Page Reference​

Navigate to Capabilities > Connections > Stock Photos to manage the integration.

Connected State​

When a connection is active, the page shows:

  • Provider - Pexels
  • Status badge - Active / Error / Disconnected
  • Connected date and last-tested timestamp
  • Test Connection button - verifies the stored key is still valid without side effects
  • Update API Key button - enter a replacement key (for example, after rotating in Pexels)
  • Agent Access section - default-on agents (read-only) and grant-gated agents (toggleable)
  • Disconnect button in the Danger Zone

Not-Connected State​

If no connection exists, the page shows an API Key input field and a Connect button.

The find_stock_photo Tool​

When the integration is active, one tool is available to agents:

find_stock_photo​

Search Pexels for a stock photo matching a description, re-host the image, and return a stable URL with attribution.

ParameterTypeRequiredDescription
querystringYesSearch terms describing the desired image (e.g., "mountain landscape sunset")
orientationstringNolandscape, portrait, or square (default: landscape)
per_pageintegerNoNumber of results to evaluate (1-10; the best match is returned)

Returns:

  • image_url - Stable SAS URL to the re-hosted image (valid for 1 hour; the image itself is kept in blob storage)
  • photographer - Pexels photographer name (required attribution)
  • photographer_url - Link to the photographer's Pexels profile
  • source_url - Original Pexels page for the photo
  • width / height - Image dimensions in pixels
warning

Pexels images are free to use but require attribution. Agent instructions should include the photographer name and source URL when embedding a photo in published content.

Security​

  • API key encrypted at rest - Stored with AES-256-CBC encryption; never returned in GET responses
  • Tenant isolation - Each tenant's key and tool are scoped by TenantId
  • Secure file storage - Re-hosted images are stored in tenant-scoped Azure Blob Storage paths
  • Time-limited access - SAS URLs expire after 1 hour with read-only HTTPS-only permissions
  • Key never logged - The Pexels API key is never written to logs or error messages

Disconnecting​

To remove the Stock Photos connection:

  1. On the connection page, scroll to the Danger Zone section.
  2. Click Disconnect.
  3. Confirm in the dialog.

The find_stock_photo tool is deleted and all agent assignments are revoked. You can reconnect at any time by entering a valid API key.

Frequently Asked Questions​

Do I need a paid Pexels plan?

No. The free Pexels API tier supports up to 20,000 requests per month and 200 per hour - sufficient for most agent usage. If your agents search for images very frequently, monitor your Pexels usage dashboard.

Why are CAIOO and Personal Assistants always enabled?

These agents are designed for proactive content creation tasks where image access is broadly useful. SME and Mailbox agents have narrower, human-facing roles so access is opt-in.

Can I connect multiple Pexels accounts?

No. One Pexels key per tenant is supported. To switch keys, click Update API Key on the connection page.

The image URL I got has expired - what should I do?

SAS URLs are valid for 1 hour. If the agent produced a URL that has since expired, instruct the agent to search again. The image is retained in blob storage; only the URL needs refreshing.

What happens if the Pexels API rate limit is hit?

The platform returns a clear error to the agent indicating rate limiting. Instruct your agents to spread image searches over time if you anticipate high volume.