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 your Civitai 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: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:

response = civitai.image.create(input)

Then, fetch the result later:

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.

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:

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.

civitai.image.create

Run a model with inputs you provide.

response = civitai.image.create(options)

Additional Networks

ControlNets

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

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:

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! 🥹🤭