API Documentation

Installation

TypeScript / JavaScript

One package with SDK, React components, and CLI:

React is an optional peer dependency — Node and CLI users don't need it.

Python

Sync and async clients with full type hints:

Use AsyncOKSLOP for async/await. Get an API key by registering a developer app.

Rate Limiting

Rate limits are enforced per API key. Current limits are communicated via response headers:

Tier Limits

Exceeding rate limits returns a 429 Too Many Requests response. Back off and retry after the reset time.

Endpoints

Downloads

To download an image, call the /api/v1/photos/:id/download endpoint (or follow the links.download_location URL from any image object). This returns a signed, time-limited URL that expires after 10 minutes.

The signed URL format is https://okslop.com/dl/{photoId}?token=...&expires=.... This prevents hotlinking and ensures all downloads are properly tracked.

This works similarly to Unsplash's download_location behavior. After receiving the signed URL, either redirect the user to it or fetch the image directly from your server.

Migrating from Unsplash

The OKSLOP API follows Unsplash's response format to make migration as straightforward as possible. If you have an existing Unsplash integration, most of your code will work with minimal changes.

The main difference: all images on OKSLOP are AI-generated, and contributor profiles map to fictional AI artist personas rather than real photographers.

SDK Migration

Replacing the deprecated unsplash-js package takes just two steps:

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with details:

NPM Client

One package, multiple entry points. Install okslop and import what you need:

React is an optional peer dependency. Node/CLI users don't need to install it.

SDK Usage

Deterministic Images (photos.seeded)

Get a stable, repeatable image for any string. The same query + seed always returns the same photo — perfect for blog hero images, email headers, or anywhere you need consistent results without storing IDs.

Placeholder Images (photos.randomUrl)

Use OKSLOP as a placeholder image service. The /img/random endpoint returns a 302 redirect to a random photo — use it directly as an <img src>. No API key required, no DB hit, instant response.

SDK Helper

The SDK provides photos.randomUrl() which builds these URLs with automatic seeding — each call produces a unique URL so the browser won't serve a cached redirect.

Helper Functions

Three static utilities that work on any Photo object — no client instance needed:

Error Handling

The SDK throws typed errors for common HTTP status codes, making it easy to handle specific error conditions:

Cancellation

All methods accept an optional signal for request cancellation via AbortController:

Custom Fetch

Supply your own fetch implementation for testing, caching, or proxying:

Async Pagination

Iterate through all results with automatic pagination using for await:

Download Helpers

Fetch image data directly without handling the two-step download flow yourself:

Auto-Retry

Automatically retry rate-limited requests with exponential backoff:

Request Hooks

Hook into the request lifecycle for logging, metrics, or custom behavior:

Embed Generation

Generate AI images on demand by submitting a prompt. Each unique combination of prompt, contributor, and orientation produces a deterministic hash ID — the same inputs always return the same image. The hash is safe for public URLs (no prompt exposed).

How it works

1. Submit a prompt via POST /api/v1/embed — get back a deterministic hash ID
2. Use GET /api/v1/embed/:hash/img as your <img> src — it redirects to the real image once ready
3. Poll GET /api/v1/embed/:hash for status updates

SDK Usage

React Components

Import from okslop/react for React components. React is an optional peer dependency — Node/CLI users won't need it.

The <OkslopEmbed> component handles submission, polling, and display automatically:

For image search and selection, use the <OkslopPicker> component:

Command Line

Search and generate images directly from your terminal. The CLI is included in the okslop package.

Search & Browse

Generate Embed URLs

Generate deterministic image URLs locally — no API call needed, same inputs always produce the same URL:

Output Formats

Use --json for machine-readable output or --md for markdown:

CLI Options

Set OKSLOP_ACCESS_KEY environment variable for higher rate limits.

AI Agents

Install OKSLOP into your AI agent and it learns to find, generate, and insert stock images automatically. No commands to memorize — just describe what you need. Pick the install that matches your agent.

For Claude

The OKSLOP plugin bundles an MCP server, a skill, and slash commands into a single install. Works on Claude Code today and Claude.ai/Cowork once listed in the plugin directory.

After install, run /okslop:find, /okslop:generate, /okslop:hero, or /okslop:cover — or just ask Claude for what you need and it picks the right tool.

For Cursor, Windsurf, and other MCP clients

The standalone MCP server exposes the same 20 image tools. Add it to your MCP client's config.

Config location varies by client — Cursor uses .cursor/mcp.json, Windsurf uses mcp_config.json. See the MCP server README for per-client instructions.

For v0, Vercel agents, and agent-skills tools

Install the skill via the agent-skills protocol.

Just ask

Once installed, talk to your agent like you normally would — every path above gives the agent the same capabilities:

What you get

• Millions of free images — AI-generated stock photos. No attribution, no fees.
• Custom generation — Describe exactly what you need and get a unique image.
• Automatic insertion — Your agent adds the right markup (Markdown, HTML, JSX) wherever it belongs.
• Multiple art styles — From clean tech to retro nostalgia to warm cottage-core.

API Key

Not needed to get started. Searching images works immediately. To generate custom images from text prompts, get a free key at okslop.com/developers/register:

Source: github.com/OKSLOP/okslop-skill

Custom Agent Config

If you prefer writing your own agent instructions instead of installing the plugin or skill, add CLI-based prompts to your CLAUDE.md, .cursorrules, or any agent config file. The snippets below are ready to paste.

Use Case: Auto-Images for Blog Posts

Let your agent automatically find and insert cover images when writing blog posts. Add this to your CLAUDE.md:

Use Case: Documentation & READMEs

Find or generate visuals for documentation. Add this to your agent config:

Use Case: General Content Creation

Full instructions for any content that needs images:

How It Works

When your agent needs an image, it runs the CLI, parses the output, and inserts the image URL into your content:

API Playground

Try the API live from your browser. Paste your API key and hit Run to see real responses with syntax-highlighted JSON.