okslop

The official Python client for OKSLOP — free, AI-generated stock photos for any project.

OKSLOP gives you instant access to a library of AI-generated images — search by keyword, filter by style, or generate exactly what you need from a text prompt. Use them in blogs, apps, docs, landing pages, social content, or anywhere you need a visual. No attribution required, no licensing fees, no hassle.

Browse photos and AI creators at okslop.com. Get your free API key to start building.

Homepage	okslop.com
Plugin Page	okslop.com/apps/python-sdk
Documentation	okslop.com/developers
PyPI	pypi.org/project/okslop
TypeScript SDK	npmjs.com/package/okslop

Installation

pip install okslop

Quick Start

from okslop import OKSLOP

# Initialize (works without API key, optional for higher limits)
client = OKSLOP()

# Or with API key
client = OKSLOP(api_key="your-api-key")

# Search for photos
result = client.photos.search(query="cozy coffee shop morning light", per_page=10)
for photo in result.results:
    print(f"{photo.id}: {photo.alt_description}")

# Get a specific photo
photo = client.photos.get("abc123")
print(photo.urls.full)

# Download to file
client.photos.download_file("abc123", "photo.webp")

# Get random photos
photos = client.photos.random(count=5)

# Generate a new image (requires API key)
result = client.embed(
    prompt="minimalist desk setup with plants",
    contributor="modern-minimal"
)

API Reference

OKSLOP(api_key=None, base_url=None)

Initialize the client.

• api_key (optional): Your API key for higher rate limits
• base_url (optional): Override API base URL (default: https://api.okslop.com/api/v1)

Photos

client.photos.search(query, page=None, per_page=None, orientation=None, sort=None, contributor=None)

Search for photos by semantic query.

Returns: SearchResult with .results list of Photo

client.photos.get(id)

Get a single photo by ID.

Returns: Photo

client.photos.list(page=None, per_page=None, sort=None)

List photos.

Returns: PaginatedPhotos

client.photos.random(count=None, query=None, orientation=None)

Get random photos.

Returns: List[Photo]

client.photos.download(id)

Get download URL for a photo.

Returns: dict with url

client.photos.download_file(id, path, size="full")

Download a photo to disk.

• size: "thumb" (400px), "small" (800px), "full" (2000px), or "raw"

Returns: Path

Categories

client.categories.list()

List all categories.

Returns: List[Category]

client.categories.get(slug)

Get a category by slug.

Returns: Category

client.categories.photos(slug, page=None, per_page=None)

Get photos in a category.

Returns: PaginatedPhotos

Collections

client.collections.list(page=None, per_page=None)

List collections.

Returns: List[Collection]

client.collections.get(slug)

Get a collection by slug.

Returns: Collection

client.collections.photos(slug, page=None, per_page=None)

Get photos in a collection.

Returns: PaginatedPhotos

Embed (Image Generation)

client.embed(prompt, contributor, orientation=None, seed=None, instant=None)

Generate a new image from a prompt. Requires API key.

Returns: EmbedResult

client.embed_batch(requests)

Generate multiple images. Requires API key.

Returns: List[EmbedResult]

Photo Object

photo.id               # Unique ID
photo.description      # Description
photo.alt_description  # Alt text
photo.width            # Width in pixels
photo.height           # Height in pixels
photo.color            # Dominant color hex
photo.urls.thumb       # 400px URL
photo.urls.small       # 800px URL
photo.urls.regular     # 1080px URL
photo.urls.full        # 2000px URL
photo.urls.raw         # Original resolution
photo.user.name        # Contributor name
photo.user.username    # Contributor username
photo.downloads        # Download count
photo.views            # View count
photo.likes            # Like count

Async Support

from okslop import AsyncOKSLOP

async def main():
    async with AsyncOKSLOP() as client:
        result = await client.photos.search(query="mountains")
        for photo in result.results:
            print(photo.id)

import asyncio
asyncio.run(main())

CLI

For CLI usage, use the npx CLI (requires Node.js):

npx okslop search "coffee shop" --limit 5
npx okslop download abc123 --output photo.webp

Development

Models are generated from packages/sdk-spec/okslop-spec.json (extracted from TypeScript SDK).

# Generate models from spec
pnpm generate

# Or directly
python3 scripts/generate.py

This generates:

• src/okslop/models.py — Pydantic models
• src/okslop/_methods.py — Method specs

Building

pnpm build   # generate + build wheel

Publishing to PyPI

./scripts/publish.sh         # publish to PyPI
./scripts/publish.sh --test  # publish to TestPyPI first

Requires TWINE_API_TOKEN env var or ~/.pypirc credentials.

Links

• OKSLOP Website
• API Documentation
• TypeScript SDK
• All Integrations

License

MIT