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.
Streamlit Demo: See the Civitai SDK in action with a live Streamlit app demo. View Streamlit Demo

Installation

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 civitai.com/user/account and set it as an environment variable:

export CIVITAI_API_TOKEN=<your token>

Requirements

Python 3.7+

Usage

Import the Civitai SDK:

import civitai

Create a txt2img job:

input = {
    "model": "urn:air:sd1:checkpoint:civitai:4201@130072",
    "params": {
        "prompt": "RAW photo, face portrait photo of 26 y.o woman, wearing black dress, happy face, hard shadows, cinematic shot, dramatic lighting",
        "negativePrompt": "(deformed iris, deformed pupils, semi-realistic, cgi, 3d, render, sketch, cartoon, drawing, anime, mutated hands and fingers:1.4), (deformed, distorted, disfigured:1.3)",
        "scheduler": "EulerA",
        "steps": 20,
        "cfgScale": 7,
        "width": 512,
        "height": 512,
        "clipSkip": 2
    }
}

Run a model:

response = civitai.image.create(input)

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:

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": {
        "urn:air:sd1:lora:civitai:162141@182559": {
            "type": "Lora",
            "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.

`civitai.image.create`

Run a model with inputs you provide.

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 \| null	Optional. The scheduler algorithm to use. 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 \| null	Optional. An associative list of additional networks, keyed by the AIR of the network. Each network is of type AssetType.
`controlNets`	Array<ImageJobControlNet> \| null	Optional. An associative list of additional networks.

Additional Networks

`additionalNetworks`	Record<string, ImageJobNetworkParams>	Optional. An associative list of additional networks, keyed by the AIR of the network. Each network is described by an `ImageJobNetworkParams` object.
`type`	`AssetType`	Optional. The type of the asset. Can be one of `Lora`, `Hypernetwork`, `TextualInversion`, `Lycoris`, `Checkpoint`, `Vae`, `LoCon`.
`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>	Optional. An array of control networks that can be applied to the image generation process. Each `ImageJobControlNet` object in the array can have the following properties:
`preprocessor`	ImageTransformer \| null	Optional. Specifies the image transformer to be applied as a preprocessor. 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.

job_id = "your_job_id_here"
response = civitai.jobs.get(id=job_id)

# OR

token = "your_token_here"
response = civitai.jobs.get(token=token)

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

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.

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:

Push your changes to your fork.
Open a pull request against the main repository.
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! 🥹🤭

Civitai Generator Python Client

Quick Start​

Installation​

Authenticate​

Requirements​

Usage​

Import the Civitai SDK:​

Create a txt2img job:​

Using Additional Networks​

civitai.image.create​

Additional Networks​

ControlNets​

civitai.jobs.get​

civitai.jobs.query​

civitai.jobs.cancel​

Contributing Your Changes​

Additional Guidelines​