Metadata-Version: 2.1
Name: civitai-api
Version: 0.1.3
Summary: Default template for PDM package
Author-Email: Pyon~ Pyon~~ <32931796+tick97115115@users.noreply.github.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: pydantic>=2.10.4
Requires-Dist: anyio>=4.7.0
Description-Content-Type: text/markdown

# civitai_api

This project provide a easy way to communicating with Civitai-API.

It supports both Sync and Async request implementation, and both Async implementation (AsyncIO and Trio) by using Anyio.

## usage

this was designed to be a flexale library, which only need you initialize an httpx library as the function's first argument.

### 1. initialize an httpx client for function use

for Sync Clinet:

```python
from civitai_api import api
import httpx

proxy = "http://127.0.0.1:7890"

# setting up your civitai api key and proxy
client = httpx.Client(headers={"Authorization": f"Bearer {api_key}"}, proxy = proxy)
# or 
with httpx.Client(headers={"Authorization": f"Bearer {api_key}"}, proxy = proxy) as client:
    ......
```

For Async Client:

```python
async_client = httpx.AsyncClient(headers={"Authorization": f"Bearer {api_key}"}, proxy = proxy)
# or 
async with httpx.AsyncClient(headers={"Authorization": f"Bearer {api_key}"}, proxy = proxy) as async_client:
    ......
```

> for more info please checkout [httpx official website](https://www.python-httpx.org/advanced/clients/).

### 2. request for certain endpoint

For a certain endpoint, there will have two functions for both sync and async implementation. And the only two differences between them were:

1. the async implementation's first argument takes async httpx client instance.
2. async implementation's function name will have 'async_' as the prefix to differenciate whether it's Sync or Async.

to be supplemented.

### 3. how to correctly write arguments

For endpoints: creators, images and models, there are 3 functions (and 3 async implementatons) takes function arguments to construct request query paramters.

and every argument value have to be enclosed by a list:

```python
response = api.get_images_v1(client, postId=[11059742], nsfw=[NsfwLevel.X.value]) 
```

That's because the httpx library have it's own way to construct query paramters.

> for more info: [query-parameters](https://www.python-httpx.org/compatibility/#query-parameters)

#### for some arguments those takes List[enum] type as input

You should always take care of when an argument takes a specific enum type as input, you should write like this:

```python
from civitai_api.models.images import NsfwLevel

......# after initialize httpx client

response = api.get_images_v1(client, postId=[11059742], nsfw=[NsfwLevel.X.value]) 
```

When an argument takes an enum type as input, you must use the 'value' property from an enum field like this:

```python
nsfw=[NsfwLevel.X.value]
```

Otherwise the query paramter's string value will have a enum class name as prefix. (which isn't a valid input for API endpoint.)
