Metadata-Version: 2.4
Name: okslop
Version: 0.0.2
Summary: Official Python SDK for OKSLOP - AI stock photos
Project-URL: Homepage, https://okslop.com
Project-URL: Documentation, https://okslop.com/developers
Project-URL: Repository, https://github.com/okslop/python-sdk
Project-URL: Issues, https://github.com/okslop/python-sdk/issues
Author-email: OKSLOP <dev@okslop.com>
License-Expression: MIT
Keywords: ai,api,images,sdk,stock-photos
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# okslop

[![OKSLOP — Python SDK](https://okslop.com/static/generated/readme/python-sdk.webp)](https://okslop.com)

The official Python client for [OKSLOP](https://okslop.com) — 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](https://okslop.com). Get your free [API key](https://okslop.com/developers) to start building.

| | |
|---|---|
| Homepage | [okslop.com](https://okslop.com) |
| Documentation | [okslop.com/developers](https://okslop.com/developers) |
| PyPI | [pypi.org/project/okslop](https://pypi.org/project/okslop) |
| TypeScript SDK | [npmjs.com/package/okslop](https://npmjs.com/package/okslop) |

## Installation

```bash
pip install okslop
```

## Quick Start

```python
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

```python
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

```python
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):

```bash
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).

```bash
# 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

```bash
pnpm build   # generate + build wheel
```

### Publishing to PyPI

```bash
./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](https://okslop.com)
- [API Documentation](https://okslop.com/developers)
- [TypeScript SDK](https://npmjs.com/package/okslop)
- [All Integrations](https://okslop.com/apps)

## License

MIT
