# Civitai Generator Python Client
A Python client for Civitai's generator to run Civitai models from your Python code.
## Quick Start
To get started with the Civitai Generator Python Client, you can use the following resources:
- **Google Colab Notebook**: Jump into a pre-configured environment with a live notebook to try out the Civitai SDK.
<a target="_blank" href="https://colab.research.google.com/github/civitai/civitai-python/blob/main/examples/text2img.ipynb">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
</a>
- **Streamlit Demo**: See the Civitai SDK in action with a live Streamlit app demo. [View Streamlit Demo](https://civitai.streamlit.app/)
## Installation
```python
pip install civitai-py
```
## Authenticate
Before running any Python scripts that use the API, you need to set your Civitai API token in your environment.
Grab your token from [your Civitai account](https://civitai.com/user/account) and set it as an environment variable:
```bash
export CIVITAI_API_TOKEN=<your token>
```
## Requirements
- Python 3.7+
## Usage
#### Import the Civitai SDK:
```python
import civitai
```
#### Create a txt2img job:
```python
input = {
"model": "urn:air:sd1:checkpoint:civitai:4384@128713",
"params": {
"prompt": "RAW photo, face portrait photo of woman, wearing black dress, happy face, hard shadows, cinematic shot, dramatic lighting",
"negativePrompt": "(deformed, distorted, disfigured:1.3)",
"scheduler": "EulerA",
"steps": 20,
"cfgScale": 7,
"width": 512,
"height": 512,
"clipSkip": 2
}
}
```
Run a model:
```python
response = civitai.image.create(input)
```
Then, fetch the result later:
```python
response = civitai.jobs.get(token=response.token)
```
Or wait for the job to finish by running the generation in the background a.k.a long polling. You can add the `wait=True` flag to the method. It has a default timeout of 5 minutes.
```python
response = civitai.image.create(input, wait=True)
```
### Using Additional Networks
The SDK supports additional networks: LoRA, VAE, Hypernetwork, Textual Inversion, LyCORIS, Checkpoint, and LoCon.
To use any of the networks availabe on Civitai, simply add the `additionalNetworks` field into the input:
```python
input = {
"model": "urn:air:sd1:checkpoint:civitai:4384@128713",
"params": {
"prompt": "masterpiece, best quality, 1girl, IncrsAhri, multiple tails, fox tail, korean clothes, skirt, braid, arms behind back",
"negativePrompt": "(worst quality:1.4), (low quality:1.4), simple background, bad anatomy",
"scheduler": "EulerA",
"steps": 25,
"cfgScale": 7,
"width": 512,
"height": 768,
"seed": -1,
"clipSkip": 2
},
"additionalNetworks": {
# Detail enhancer LoRA: https://civitai.com/models/82098/add-more-details-detail-enhancer-tweaker-lora
"urn:air:sd1:lora:civitai:82098@87153": {
"strength": 1.0
}
}
}
```
In the case of `Lora` and `LoCon` networks, set the `strength` of the network; for `TextualInversion`, set the `triggerWord` of the network.
<br/>
### `civitai.image.create`
Run a model with inputs you provide.
```python
response = civitai.image.create(options)
```
| name | type | description |
| ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | string \| null | **Required**. The Civitai model to use for generation. |
| `params.prompt` | string \| null | **Required**. The main prompt for the image generation. |
| `params.negativePrompt` | string \| null | Optional. The negative prompt for the image generation. |
| `params.scheduler` | [Scheduler](civitai/models/Scheduler.py) \| null | Optional. The scheduler algorithm to use. <br/> <br/>Possible values are: `EulerA`, `Euler`, `LMS`, `Heun`, `DPM2`, `DPM2A`, `DPM2SA`, `DPM2M`, `DPMSDE`, `DPMFast`, `DPMAdaptive`, `LMSKarras`, `DPM2Karras`, `DPM2AKarras`, `DPM2SAKarras`, `DPM2MKarras`, `DPMSDEKarras`, `DDIM`, `PLMS`, `UniPC`, `Undefined`, `LCM`, `DDPM`, `DEIS`. |
| `params.steps` | number \| null | Optional. The number of steps for the image generation process. |
| `params.cfgScale` | number \| null | Optional. The CFG scale for the image generation. |
| `params.width` | number | **Required**. The width of the generated image. |
| `params.height` | number | **Required**. The height of the generated image. |
| `params.seed` | number \| null | Optional. The seed for the image generation process. |
| `params.clipSkip` | number \| null | Optional. The number of CLIP skips for the image generation. |
| `callbackUrl` | string \| null | Optional. URL that will be invoked upon completion of this job |
| `additionalNetworks` | [ImageJobNetworkParams](civitai/models/ImageJobNetworkParams.py) \| null | Optional. An associative list of additional networks, keyed by the AIR of the network. Each network is of type [AssetType](civitai/models/asset_type.py). |
| `controlNets` | Array<[ImageJobControlNet](civitai/models/ImageJobControlNet.py)> \| null | Optional. An associative list of additional networks. |
#### Additional Networks
| `additionalNetworks` | Record<string, [ImageJobNetworkParams](civitai/models/ImageJobNetworkParams.py)> | Optional. An associative list of additional networks, keyed by the AIR of the network. Each network is described by an `ImageJobNetworkParams` object. |
| -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `strength` | number | Optional. In case of Lora and LoCon, set the strength of the network. |
| `triggerWord` | string | Optional. In case of a TextualInversion, set the trigger word of the network. |
#### ControlNets
| `controlNets` | Array<[ImageJobControlNet](civitai/models/ImageJobControlNet.py)> | Optional. An array of control networks that can be applied to the image generation process. <br/><br/>Each `ImageJobControlNet` object in the array can have the following properties: |
| -------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preprocessor` | [ImageTransformer](civitai/models/ImageTransformer.py) \| null | Optional. Specifies the image transformer to be applied as a preprocessor. <br/><br/>Possible values are `Canny`, `DepthZoe`, `SoftedgePidinet`, `Rembg`. |
| `weight` | number \| null | Optional. The weight of the control net. |
| `startStep` | number \| null | Optional. The step at which the control net starts to apply. |
| `endStep` | number \| null | Optional. The step at which the control net stops applying. |
| `imageUrl` | string \| null | Optional. The URL of the image associated with the controlnet. |
### `civitai.jobs.get`
Fetches job details based on a provided token or job ID. If both are provided, the token takes precedence.
```python
job_id = "your_job_id_here"
response = civitai.jobs.get(job_id=job_id)
# OR
token = "your_token_here"
response = civitai.jobs.get(token=token)
# OR
response = civitai.jobs.get(token=token, job_id=job_id)
```
### `civitai.jobs.query`
Retrieve a collection of jobs by querying properties, e.g., userId. You can optionally include a `detailed` boolean flag to get detailed information about the jobs.
```python
query = {
"properties": {
"userId": 4 # Querying by userId
}
}
detailed = False # Optional boolean flag to get detailed job definitions. False by default.
response = civitai.jobs.query(detailed=detailed, query_jobs_request=query)
```
### `civitai.jobs.cancel`
Cancel a job by its jobId.
```python
response = civitai.jobs.cancel(job_id)
```
This method cancels a job that is currently scheduled or running. It requires the `jobId` of the job you wish to cancel. On successful cancellation, it returns a response object indicating the cancellation status.
### Contributing Your Changes
After making your changes:
1. Push your changes to your fork.
2. Open a pull request against the main repository.
3. Describe your changes and how they improve the project or fix issues.
Your contributions will be reviewed, and if accepted, merged into the project.
### Additional Guidelines
- Include unit tests for new features or bug fixes.
- Update the documentation if necessary.
Thank you for contributing to the Civitai Generator Python Client! 🥹ðŸ¤
Raw data
{
"_id": null,
"home_page": "https://github.com/civitai/civitai-python",
"name": "civitai-py",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": null,
"keywords": "Civitai Python SDK, Civitai",
"author": "Civitai",
"author_email": "hello@civitai.com",
"download_url": "https://files.pythonhosted.org/packages/2e/e9/c10e42961bfb51aa0eb8d93698352907ec87e0b8d62dea1fdc4159ea5c4e/civitai_py-0.1.10.tar.gz",
"platform": null,
"description": "# Civitai Generator Python Client\n\nA Python client for Civitai's generator to run Civitai models from your Python code.\n\n## Quick Start\n\nTo get started with the Civitai Generator Python Client, you can use the following resources:\n\n- **Google Colab Notebook**: Jump into a pre-configured environment with a live notebook to try out the Civitai SDK.\n\n <a target=\"_blank\" href=\"https://colab.research.google.com/github/civitai/civitai-python/blob/main/examples/text2img.ipynb\">\n <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n</a>\n\n- **Streamlit Demo**: See the Civitai SDK in action with a live Streamlit app demo. [View Streamlit Demo](https://civitai.streamlit.app/)\n\n## Installation\n\n```python\npip install civitai-py\n```\n\n## Authenticate\n\nBefore running any Python scripts that use the API, you need to set your Civitai API token in your environment.\n\nGrab your token from [your Civitai account](https://civitai.com/user/account) and set it as an environment variable:\n\n```bash\nexport CIVITAI_API_TOKEN=<your token>\n```\n\n## Requirements\n\n- Python 3.7+\n\n## Usage\n\n#### Import the Civitai SDK:\n\n```python\nimport civitai\n```\n\n#### Create a txt2img job:\n\n```python\ninput = {\n \"model\": \"urn:air:sd1:checkpoint:civitai:4384@128713\",\n \"params\": {\n \"prompt\": \"RAW photo, face portrait photo of woman, wearing black dress, happy face, hard shadows, cinematic shot, dramatic lighting\",\n \"negativePrompt\": \"(deformed, distorted, disfigured:1.3)\",\n \"scheduler\": \"EulerA\",\n \"steps\": 20,\n \"cfgScale\": 7,\n \"width\": 512,\n \"height\": 512,\n \"clipSkip\": 2\n }\n}\n```\n\nRun a model:\n\n```python\nresponse = civitai.image.create(input)\n```\n\nThen, fetch the result later:\n\n```python\nresponse = civitai.jobs.get(token=response.token)\n```\n\nOr wait for the job to finish by running the generation in the background a.k.a long polling. You can add the `wait=True` flag to the method. It has a default timeout of 5 minutes.\n\n```python\nresponse = civitai.image.create(input, wait=True)\n```\n\n### Using Additional Networks\n\nThe SDK supports additional networks: LoRA, VAE, Hypernetwork, Textual Inversion, LyCORIS, Checkpoint, and LoCon.\n\nTo use any of the networks availabe on Civitai, simply add the `additionalNetworks` field into the input:\n\n```python\ninput = {\n \"model\": \"urn:air:sd1:checkpoint:civitai:4384@128713\",\n \"params\": {\n \"prompt\": \"masterpiece, best quality, 1girl, IncrsAhri, multiple tails, fox tail, korean clothes, skirt, braid, arms behind back\",\n \"negativePrompt\": \"(worst quality:1.4), (low quality:1.4), simple background, bad anatomy\",\n \"scheduler\": \"EulerA\",\n \"steps\": 25,\n \"cfgScale\": 7,\n \"width\": 512,\n \"height\": 768,\n \"seed\": -1,\n \"clipSkip\": 2\n },\n \"additionalNetworks\": {\n # Detail enhancer LoRA: https://civitai.com/models/82098/add-more-details-detail-enhancer-tweaker-lora\n \"urn:air:sd1:lora:civitai:82098@87153\": {\n \"strength\": 1.0\n }\n }\n}\n```\n\nIn the case of `Lora` and `LoCon` networks, set the `strength` of the network; for `TextualInversion`, set the `triggerWord` of the network.\n\n<br/>\n\n### `civitai.image.create`\n\nRun a model with inputs you provide.\n\n```python\nresponse = civitai.image.create(options)\n```\n\n| name | type | description |\n| ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `model` | string \\| null | **Required**. The Civitai model to use for generation. |\n| `params.prompt` | string \\| null | **Required**. The main prompt for the image generation. |\n| `params.negativePrompt` | string \\| null | Optional. The negative prompt for the image generation. |\n| `params.scheduler` | [Scheduler](civitai/models/Scheduler.py) \\| null | Optional. The scheduler algorithm to use. <br/> <br/>Possible values are: `EulerA`, `Euler`, `LMS`, `Heun`, `DPM2`, `DPM2A`, `DPM2SA`, `DPM2M`, `DPMSDE`, `DPMFast`, `DPMAdaptive`, `LMSKarras`, `DPM2Karras`, `DPM2AKarras`, `DPM2SAKarras`, `DPM2MKarras`, `DPMSDEKarras`, `DDIM`, `PLMS`, `UniPC`, `Undefined`, `LCM`, `DDPM`, `DEIS`. |\n| `params.steps` | number \\| null | Optional. The number of steps for the image generation process. |\n| `params.cfgScale` | number \\| null | Optional. The CFG scale for the image generation. |\n| `params.width` | number | **Required**. The width of the generated image. |\n| `params.height` | number | **Required**. The height of the generated image. |\n| `params.seed` | number \\| null | Optional. The seed for the image generation process. |\n| `params.clipSkip` | number \\| null | Optional. The number of CLIP skips for the image generation. |\n| `callbackUrl` | string \\| null | Optional. URL that will be invoked upon completion of this job |\n| `additionalNetworks` | [ImageJobNetworkParams](civitai/models/ImageJobNetworkParams.py) \\| null | Optional. An associative list of additional networks, keyed by the AIR of the network. Each network is of type [AssetType](civitai/models/asset_type.py). |\n| `controlNets` | Array<[ImageJobControlNet](civitai/models/ImageJobControlNet.py)> \\| null | Optional. An associative list of additional networks. |\n\n#### Additional Networks\n\n| `additionalNetworks` | Record<string, [ImageJobNetworkParams](civitai/models/ImageJobNetworkParams.py)> | Optional. An associative list of additional networks, keyed by the AIR of the network. Each network is described by an `ImageJobNetworkParams` object. |\n| -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `strength` | number | Optional. In case of Lora and LoCon, set the strength of the network. |\n| `triggerWord` | string | Optional. In case of a TextualInversion, set the trigger word of the network. |\n\n#### ControlNets\n\n| `controlNets` | Array<[ImageJobControlNet](civitai/models/ImageJobControlNet.py)> | Optional. An array of control networks that can be applied to the image generation process. <br/><br/>Each `ImageJobControlNet` object in the array can have the following properties: |\n| -------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `preprocessor` | [ImageTransformer](civitai/models/ImageTransformer.py) \\| null | Optional. Specifies the image transformer to be applied as a preprocessor. <br/><br/>Possible values are `Canny`, `DepthZoe`, `SoftedgePidinet`, `Rembg`. |\n| `weight` | number \\| null | Optional. The weight of the control net. |\n| `startStep` | number \\| null | Optional. The step at which the control net starts to apply. |\n| `endStep` | number \\| null | Optional. The step at which the control net stops applying. |\n| `imageUrl` | string \\| null | Optional. The URL of the image associated with the controlnet. |\n\n### `civitai.jobs.get`\n\nFetches job details based on a provided token or job ID. If both are provided, the token takes precedence.\n\n```python\njob_id = \"your_job_id_here\"\nresponse = civitai.jobs.get(job_id=job_id)\n\n# OR\n\ntoken = \"your_token_here\"\nresponse = civitai.jobs.get(token=token)\n\n# OR\n\nresponse = civitai.jobs.get(token=token, job_id=job_id)\n```\n\n### `civitai.jobs.query`\n\nRetrieve a collection of jobs by querying properties, e.g., userId. You can optionally include a `detailed` boolean flag to get detailed information about the jobs.\n\n```python\nquery = {\n \"properties\": {\n \"userId\": 4 # Querying by userId\n }\n}\n\ndetailed = False # Optional boolean flag to get detailed job definitions. False by default.\n\nresponse = civitai.jobs.query(detailed=detailed, query_jobs_request=query)\n```\n\n### `civitai.jobs.cancel`\n\nCancel a job by its jobId.\n\n```python\nresponse = civitai.jobs.cancel(job_id)\n\n```\n\nThis method cancels a job that is currently scheduled or running. It requires the `jobId` of the job you wish to cancel. On successful cancellation, it returns a response object indicating the cancellation status.\n\n### Contributing Your Changes\n\nAfter making your changes:\n\n1. Push your changes to your fork.\n2. Open a pull request against the main repository.\n3. Describe your changes and how they improve the project or fix issues.\n\nYour contributions will be reviewed, and if accepted, merged into the project.\n\n### Additional Guidelines\n\n- Include unit tests for new features or bug fixes.\n- Update the documentation if necessary.\n\nThank you for contributing to the Civitai Generator Python Client! \ud83e\udd79\ud83e\udd2d\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Civitai Python SDK",
"version": "0.1.10",
"project_urls": {
"Homepage": "https://github.com/civitai/civitai-python",
"Repository": "https://github.com/civitai/civitai-python"
},
"split_keywords": [
"civitai python sdk",
" civitai"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca623db1ca45499cc580556b5c54fd94d147980afcee88e4c059a1f28da8aea1",
"md5": "1819e3d7e0da83ac088e275adf3f4e4e",
"sha256": "891bb17dc90cf5e4cba30289d8d1c13c76d67e076f2f8837765d852acaeff526"
},
"downloads": -1,
"filename": "civitai_py-0.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1819e3d7e0da83ac088e275adf3f4e4e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 61714,
"upload_time": "2024-06-24T17:49:49",
"upload_time_iso_8601": "2024-06-24T17:49:49.380051Z",
"url": "https://files.pythonhosted.org/packages/ca/62/3db1ca45499cc580556b5c54fd94d147980afcee88e4c059a1f28da8aea1/civitai_py-0.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ee9c10e42961bfb51aa0eb8d93698352907ec87e0b8d62dea1fdc4159ea5c4e",
"md5": "9805f97ae70605d556e41fca5ded4a45",
"sha256": "ded62f751340259166feb343815a64f6e9af70cb4547e72c4caf3338549faae2"
},
"downloads": -1,
"filename": "civitai_py-0.1.10.tar.gz",
"has_sig": false,
"md5_digest": "9805f97ae70605d556e41fca5ded4a45",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 27760,
"upload_time": "2024-06-24T17:49:51",
"upload_time_iso_8601": "2024-06-24T17:49:51.641078Z",
"url": "https://files.pythonhosted.org/packages/2e/e9/c10e42961bfb51aa0eb8d93698352907ec87e0b8d62dea1fdc4159ea5c4e/civitai_py-0.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-24 17:49:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "civitai",
"github_project": "civitai-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "setuptools",
"specs": [
[
">=",
"21.0.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"<",
"2.1.0"
],
[
">=",
"1.25.3"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.7.1"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.23.3"
]
]
}
],
"lcname": "civitai-py"
}
JSON
