Metadata-Version: 2.4
Name: okslop
Version: 0.0.1
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 Python SDK

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

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

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

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

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