okslop 0.0.1

Official Python SDK for OKSLOP - AI stock photos

OKSLOP Python SDK

Official Python SDK for the OKSLOP API. Search, download, and generate AI stock photos.

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
photos = client.search("cozy coffee shop morning light", limit=10)
for photo in photos:
    print(f"{photo.id}: {photo.alt}")

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

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

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

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://okslop.com/api/v1)

client.search(query, limit=24, page=1)

Search for photos by semantic query.

Returns: List[Photo]

client.get_photo(photo_id)

Get a single photo by ID.

Returns: Photo

client.download(photo_id, path, size="full")

Download a photo to disk.

• size: "thumb" (400px), "preview" (800px), "full" (2000px), or "original"

client.generate(prompt, contributor=None)

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

Returns: Photo

client.random(count=1)

Get random photos.

Returns: List[Photo]

Photo Object

photo.id          # Unique ID
photo.alt         # Alt text / description
photo.width       # Width in pixels
photo.height      # Height in pixels
photo.urls.thumb  # 400px URL
photo.urls.preview # 800px URL
photo.urls.full   # 2000px URL
photo.urls.original # Original resolution
photo.contributor.name  # Artist name
photo.contributor.slug  # Artist slug

Async Support

from okslop import AsyncOKSLOP

async def main():
    client = AsyncOKSLOP()
    photos = await client.search("mountains")
    print(photos)

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