A node.js client for Civitai's generator to run Civitai models from your Node.js code.
npm install civitai// ESM (where `"type": module` in package.json or using .mjs extension)
import { Civitai } from "civitai";
// CommonJS (using .cjs extension)
const Civitai = require("civitai");const civitai = new Civitai({
auth: "YOUR_API_TOKEN",
});import { Scheduler } from "civitai";
const input = {
model: "urn:air:sdxl:checkpoint:civitai:101055@128078",
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: Scheduler.EULER_A,
steps: 20,
cfgScale: 7,
width: 512,
height: 512,
clipSkip: 2,
},
};Run a model:
const response = await civitai.image.fromText(input);Then fetch the result later:
const output = civitai.jobs.get(response.token);Or wait for the job to finish by running the generation in the background a.k.a long polling:
const response = await civitai.image.fromText(input, true); // Add true flagNote: Jobs timeout after 10 minutes.
The SDK supports additional networks: LoRA, VAE, Hypernetwork, Textual Inversion, LyCORIS, Checkpoint, and LoCon. See the full list here.
To use any of the networks availabe on Civitai, simply add the additionalNetworks field into the input:
import { Scheduler, AssetType } from "civitai";
const 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: Scheduler.EULER_A,
steps: 25,
cfgScale: 7,
width: 512,
height: 768,
seed: -1,
clipSkip: 2,
},
// Add this `additionalNetworks` field
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.
const civitai = new Civitai(options);| name | type | description |
|---|---|---|
auth |
string | Required. API access token |
env |
dev | production |
Optional. The environment to use. Default is production. |
Run a model with inputs you provide.
const response = await civitai.image.fromText(options);{
"token": "W3siSm9icyI6WyJjYzJkOGViNy1mOGE0LTRkNzYtOTE3Yi01OTliODRiZmRmNmYiXX1d",
"jobs": [
{
"jobId": "cc2d8eb7-f8a4-4d76-917b-599b84bfdf6f",
"cost": 1.2000000000000002,
"result": {
"blobKey": "0B60A87CDFB8E7307D0F19F623EBD8240307BD9C2345CD03B7E52A489A52CC47",
"available": false
},
"scheduled": true
}
]
}| 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. |
batchSize |
number | null | Optional. The number of images to generate in a single batch. |
Fetches the status of a job by its unique jobId.
const response = await civitai.jobs.getById(jobId);{
"jobId": "3f071548-46c6-40d5-8e5a-210aa6b8bccc",
"cost": 1.2000000000000002,
"result": {
"blobKey": "27E0CD13EC240389EFB9A9C25EB29DC3B4AB74A973F132D6A6DB076C8B210570",
"available": true,
"blobUrl": "https://blobs-temp.sfo3...",
"blobUrlExpirationDate": "2024-03-04T08:04:02.4149309Z"
},
"scheduled": false
}Get jobs associated with a token.
const response = await civitai.jobs.getByToken(token);{
"token": "W3siSm9icyI6WyIzZjA3MTU0OC00NmM2LTQwZDUtOGU1YS0yMTBhYTZiOGJjY2MiXX1d",
"jobs": [
{
"jobId": "3f071548-46c6-40d5-8e5a-210aa6b8bccc",
"cost": 1.2000000000000002,
"result": {
"blobKey": "27E0CD13EC240389EFB9A9C25EB29DC3B4AB74A973F132D6A6DB076C8B210570",
"available": true,
"blobUrl": "https://blobs-temp.sfo3...",
"blobUrlExpirationDate": "2024-03-04T08:00:44.8268514Z"
},
"scheduled": false
}
]
}Retrieve a collection of jobs by quering properties, e.g., userId. You can optionally include a detailed boolean flag to get detailed information about the jobs.
const query: QueryJobsRequest = {
properties: {
userId: 4, // Querying by userId
},
};
const detailed = false; // Optional boolean flag to get detailed job definitions. False by default.
const response = await civitai.jobs.getByQuery(query, detailed);{
"jobs": [
{
"jobId": "AA588B7B3EC68D88A02501121A08499E4B41664820C0F8D12F4119D8C49C04C9",
"cost": 1.54375,
"properties": {
"userId": 4,
"requestId": -1,
"RequestId": "eb6a8c28-c806-42e2-a349-5325702a1a96"
},
"result": {
"blobKey": "AA588B7B3EC68D88A02501121A08499E4B41664820C0F8D12F4119D8C49C04C9",
"available": false
},
"serviceProviders": {},
"scheduled": false
},
{
"jobId": "59B1C81ACFA3E55B9C60BCB6472DF271F3698CC0FFE154E76C7B27D5AD1934AF",
"cost": 1.54375,
"properties": {
"userId": 4,
"requestId": -1,
"RequestId": "eb6a8c28-c806-42e2-a349-5325702a1a96"
}
}
]
}Cancel a job by its jobId.
const response = await civitai.jobs.cancel(jobId);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.
Example response:
{
"status": 200,
}To check the coverage of specific models, you can use the civitai.models.get method. This method retrieves the availability of the requested models.
const models = [
"urn:air:sd1:checkpoint:civitai:107842@275408",
"urn:air:sd1:lora:civitai:162141@182559",
];
const coverage = await civitai.models.get(models);
console.log("Model coverage: ", coverage);{
"urn:air:sd1:checkpoint:civitai:107842@275408": {
"availability": "Unavailable",
"workers": 0
},
"urn:air:sd1:lora:civitai:162141@182559": {
"availability": "Available",
"workers": 1
}
}Webhooks provide real-time updates about your generation. Specify an endpoint when you create a generation, and Civitai will send HTTP POST requests to that URL when the generation is completed.
Some scenarios where webhooks are useful:
- Sending notifications when long-running generations finish. Some predictions like training jobs can take several minutes to run. You can use a webhook handler to send a notification like an email or a Slack message when a prediction completes.
- Creating model pipelines. You can use webhooks to capture the output of one long-running prediction and pipe it into another model as input.
Note: Webhooks are handy, but they’re not strictly necessary to use Civitai SDK, and there are other ways to receive updates. You can also poll the generation API check the status of a generation over time.
To use webhooks, specify a webhook URL in the request body when creating a generation.
Here’s an example using the Civitai JavaScript client:
await civitai.image.fromText({
input: {
model: "urn:air:sd1:checkpoint:civitai:4384@128713",
params: {
prompt: "a cat in a field of flowers",
...
},
webhook: "https://example.com/webhook",
}
});Here’s an example of a Next.js webhook handler:
// app/api/webhook/route.ts
import { NextResponse } from "next/server";
export async function POST(req: Request) {
try {
const data = await req.json();
if (data) {
return NextResponse.json(
{
success: true,
message: "Webhook received successfully",
data,
},
{ status: 200 }
);
} else {
return new Response("Missing output", { status: 400 });
}
} catch (error) {
console.error("Error handling webhook data:", error);
return NextResponse.json(
{ error: "Internal Server Error", message: error },
{ status: 500 }
);
}
}By default, Civitai sends requests to your webhook URL whenever there are new outputs or the generation has finished.
Your endpoint should respond with a 2xx status code within a few seconds, otherwise the webhook might be retried.
When writing the code for your new webhook handler, it’s useful to be able to receive real webhooks in your development environment so you can verify your code is handling them as expected.
ngrok is a free reverse proxy tool that can create a secure tunnel to your local machine so you can receive webhooks. If you have Node.js installed, run ngrok directly from the command line using the npx command that’s included with Node.js.
npx ngrok http 3000
The command above will generate output that looks like this:
Session Status online
Session Expires 1 hour, 59 minutes
Version 2.3.41
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://3e48-20-171-41-18.ngrok.io -> http://localhost:3000
Forwarding https://3e48-20-171-41-18.ngrok.io -> http://localhost:3000Here’s an example using the civitai JavaScript client:
await civitai.image.fromText({
input: {
model: "urn:air:sd1:checkpoint:civitai:4384@128713",
params: {
prompt: "a cat in a field of flowers",
...
},
webhook: "https://3e48-20-171-41-18.ngrok.io/api/webhooks",
}
});Your webhook handler should now receive webhooks from Civitai. Once you’ve deployed your app, change the value of the webhook URL to your production webhook handler endpoint when creating generations.
Build a web app with Next.js App Router
Contributions to the Civitai Generator Node.js Client are welcome! Here's how you can contribute or build the project from source.
- Node.js (version specified in
package.jsonunderengines.node) - npm or yarn (version specified in
package.jsonunderengines.npmorengines.yarn)
- Fork and clone the repository.
- Install dependencies:
npm installTo build the project from source:
npm run buildThis will compile the TypeScript files and generate the necessary JavaScript files in the dist directory.
- Create a
.env.testfile in the root directory and add your Civitai API token, i.e.,CIVITAI_API_TOKEN.
To ensure your changes don't break existing functionality, run the tests:
npm run testAfter 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.
- Include unit tests for new features or bug fixes.
- Update the documentation if necessary.
Thank you for contributing to the Civitai Generator Node.js Client! 🥹🤭