Civitai API

This article describes how to use the Civitai REST API. We are going to be describing the HTTP method, path, and parameters for every operation. The API will return the response status code, response headers, and a response body.

Civitai API v1

Creators

• GET /api/v1/creators

Images

• GET /api/v1/images

Models

• GET /api/v1/models

Model

• GET /api/v1/models/:modelId

Model Version

• GET /api/v1/model-versions/:modelVersionId
• GET /api/v1/model-versions/by-hash/:hash

Tags

• GET /api/v1/tags

GET /api/v1/creators

Endpoint URL

https://civitai.com/api/v1/creators

Query Parameters

Name	Type	Description
limit (OPTIONAL)	number	The number of results to be returned per page. This can be a number between 0 and 200. By default, each page will return 20 results. If set to 0, it'll return all the creators
page (OPTIONAL)	number	The page from which to start fetching creators
query (OPTIONAL)	string	Search query to filter creators by username

Response Fields

Name	Type	Description
username	string	The username of the creator
modelCount	number	The amount of models linked to this user
link	string	Url to get all models from this user
metadata.totalItems	string	The total number of items available
metadata.currentPage	string	The the current page you are at
metadata.pageSize	string	The the size of the batch
metadata.totalPages	string	The total number of pages
metadata.nextPage	string	The url to get the next batch of items
metadata.prevPage	string	The url to get the previous batch of items

Example

The following example shows a request to get the first 3 model tags from our database:

curl https://civitai.com/api/v1/creators?limit=3 \
-H "Content-Type: application/json" \
-X GET

This would yield the following response:

{
  "items": [
    {
      "username": "Civitai",
      "modelCount": 848,
      "link": "https://civitai.com/api/v1/models?username=Civitai"
    },
    {
      "username": "JustMaier",
      "modelCount": 8,
      "link": "https://civitai.com/api/v1/models?username=JustMaier"
    },
    {
      "username": "maxhulker",
      "modelCount": 2,
      "link": "https://civitai.com/api/v1/models?username=maxhulker"
    }
  ],
  "metadata": {
    "totalItems": 46,
    "currentPage": 1,
    "pageSize": 3,
    "totalPages": 16,
    "nextPage": "https://civitai.com/api/v1/creators?limit=3&page=2"
  }
}

GET /api/v1/images

Endpoint URL

https://civitai.com/api/v1/images

Query Parameters

Name	Type	Description
limit (OPTIONAL)	number	The number of results to be returned per page. This can be a number between 0 and 200. By default, each page will return 100 results.
postId (OPTIONAL)	number	The ID of a post to get images from
modelId (OPTIONAL)	number	The ID of a model to get images from (model gallery)
modelVersionId (OPTIONAL)	number	The ID of a model version to get images from (model gallery filtered to version)
username (OPTIONAL)	string	Filter to images from a specific user
nsfw (OPTIONAL)	boolean | enum (None, Soft, Mature, X)	Filter to images that contain mature content flags or not (undefined returns all)
sort (OPTIONAL)	enum (Most Reactions, Most Comments, Newest)	The order in which you wish to sort the results
period (OPTIONAL)	enum (AllTime, Year, Month, Week, Day)	The time frame in which the images will be sorted
page (OPTIONAL)	number	The page from which to start fetching creators

Response Fields

Name	Type	Description
id	number	The id of the image
url	string	The url of the image at it's source resolution
hash	string	The blurhash of the image
width	number	The width of the image
height	number	The height of the image
nsfw	boolean	If the image has any mature content labels
nsfwLevel	enum (None, Soft, Mature, X)	The NSFW level of the image
createdAt	date	The date the image was posted
postId	number	The ID of the post the image belongs to
stats.cryCount	number	The number of cry reactions
stats.laughCount	number	The number of laugh reactions
stats.likeCount	number	The number of like reactions
stats.heartCount	number	The number of heart reactions
stats.commentCount	number	The number of comment reactions
meta	object	The generation parameters parsed or input for the image
username	string	The username of the creator
metadata.nextCursor	number	The id of the first image in the next batch
metadata.currentPage	number	The the current page you are at (if paging)
metadata.pageSize	number	The the size of the batch (if paging)
metadata.nextPage	string	The url to get the next batch of items

Example

The following example shows a request to get the first image:

curl https://civitai.com/api/v1/images?limit=1 \
-H "Content-Type: application/json" \
-X GET

This would yield the following response:

Notes:

• On July 2, 2023 we switch from a paging system to a cursor based system due to the volume of data and requests for this endpoint.
• Whether you use paging or cursors, you can use metadata.nextPage to get the next page of results

GET /api/v1/models

Endpoint URL

https://civitai.com/api/v1/models

Query Parameters

Name	Type	Description
limit (OPTIONAL)	number	The number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results
page (OPTIONAL)	number	The page from which to start fetching models
query (OPTIONAL)	string	Search query to filter models by name
tag (OPTIONAL)	string	Search query to filter models by tag
username (OPTIONAL)	string	Search query to filter models by user
types (OPTIONAL)	enum[] (Checkpoint, TextualInversion, Hypernetwork, AestheticGradient, LORA, Controlnet, Poses)	The type of model you want to filter with. If none is specified, it will return all types
sort (OPTIONAL)	enum (Highest Rated, Most Downloaded, Newest)	The order in which you wish to sort the results
period (OPTIONAL)	enum (AllTime, Year, Month, Week, Day)	The time frame in which the models will be sorted
rating (OPTIONAL)	number	The rating you wish to filter the models with. If none is specified, it will return models with any rating
favorites (OPTIONAL) (AUTHED)	boolean	Filter to favorites of the authenticated user (this requires an API token or session cookie)
hidden (OPTIONAL) (AUTHED)	boolean	Filter to hidden models of the authenticated user (this requires an API token or session cookie)
primaryFileOnly (OPTIONAL)	boolean	Only include the primary file for each model (This will use your preferred format options if you use an API token or session cookie)
allowNoCredit (OPTIONAL)	boolean	Filter to models that require or don't require crediting the creator
allowDerivatives (OPTIONAL)	boolean	Filter to models that allow or don't allow creating derivatives
allowDifferentLicenses (OPTIONAL)	boolean	Filter to models that allow or don't allow derivatives to have a different license
allowCommercialUse (OPTIONAL)	enum (None, Image, Rent, Sell)	Filter to models based on their commercial permissions
nsfw (OPTIONAL)	boolean	If false, will return safer images and hide models that don't have safe images

Response Fields

Name	Type	Description
id	number	The identifier for the model
name	string	The name of the model
description	string	The description of the model (HTML)
type	enum (Checkpoint, TextualInversion, Hypernetwork, AestheticGradient, LORA, Controlnet, Poses)	The model type
nsfw	boolean	Whether the model is NSFW or not
tags	string[]	The tags associated with the model
mode	enum (Archived, TakenDown) | null	The mode in which the model is currently on. If Archived, files field will be empty. If TakenDown, images field will be empty
creator.username	string	The name of the creator
creator.image	string | null	The url of the creators avatar
stats.downloadCount	number	The number of downloads the model has
stats.favoriteCount	number	The number of favorites the model has
stats.commentCount	number	The number of comments the model has
stats.ratingCount	number	The number of ratings the model has
stats.rating	number	The average rating of the model
modelVersions.id	number	The identifier for the model version
modelVersions.name	string	The name of the model version
modelVersions.description	string	The description of the model version (usually a changelog)
modelVersions.createdAt	Date	The date in which the version was created
modelVersions.downloadUrl	string	The download url to get the model file for this specific version
modelVersions.trainedWords	string[]	The words used to trigger the model
modelVersions.files.sizeKb	number	The size of the model file
modelVersions.files.pickleScanResult	string	Status of the pickle scan ('Pending', 'Success', 'Danger', 'Error')
modelVersions.files.virusScanResult	string	Status of the virus scan ('Pending', 'Success', 'Danger', 'Error')
modelVersions.files.scannedAt	Date | null	The date in which the file was scanned
modelVersions.files.primary	boolean | undefined	If the file is the primary file for the model version
modelVersions.files.metadata.fp	enum (fp16, fp32) | undefined	The specified floating point for the file
modelVersions.files.metadata.size	enum (full, pruned) | undefined	The specified model size for the file
modelVersions.files.metadata.format	enum (SafeTensor, PickleTensor, Other) | undefined	The specified model format for the file
modelVersions.images.id	string	The id for the image
modelVersions.images.url	string	The url for the image
modelVersions.images.nsfw	string	Whether or not the image is NSFW (note: if the model is NSFW, treat all images on the model as NSFW)
modelVersions.images.width	number	The original width of the image
modelVersions.images.height	number	The original height of the image
modelVersions.images.hash	string	The blurhash of the image
modelVersions.images.meta	object | null	The generation params of the image
modelVersions.stats.downloadCount	number	The number of downloads the model has
modelVersions.stats.ratingCount	number	The number of ratings the model has
modelVersions.stats.rating	number	The average rating of the model
metadata.totalItems	string	The total number of items available
metadata.currentPage	string	The the current page you are at
metadata.pageSize	string	The the size of the batch
metadata.totalPages	string	The total number of pages
metadata.nextPage	string	The url to get the next batch of items
metadata.prevPage	string	The url to get the previous batch of items

Note: The download url uses a content-disposition header to set the filename correctly. Be sure to enable that header when fetching the download. For example, with wget:

wget https://civitai.com/api/download/models/{modelVersionId} --content-disposition

Example

The following example shows a request to get the first 3 TextualInversion models from our database:

curl https://civitai.com/api/v1/models?limit=3&types=TextualInversion \
-H "Content-Type: application/json" \
-X GET

This would yield the following response:

GET /api/v1/models/:modelId

Endpoint URL

https://civitai.com/api/v1/models/:modelId

Response Fields

Name	Type	Description
id	number	The identifier for the model
name	string	The name of the model
description	string	The description of the model (HTML)
type	enum (Checkpoint, TextualInversion, Hypernetwork, AestheticGradient, LORA, Controlnet, Poses)	The model type
nsfw	boolean	Whether the model is NSFW or not
tags	string[]	The tags associated with the model
mode	enum (Archived, TakenDown) | null	The mode in which the model is currently on. If Archived, files field will be empty. If TakenDown, images field will be empty
creator.username	string	The name of the creator
creator.image	string | null	The url of the creators avatar
modelVersions.id	number	The identifier for the model version
modelVersions.name	string	The name of the model version
modelVersions.description	string	The description of the model version (usually a changelog)
modelVersions.createdAt	Date	The date in which the version was created
modelVersions.downloadUrl	string	The download url to get the model file for this specific version
modelVersions.trainedWords	string[]	The words used to trigger the model
modelVersions.files.sizeKb	number	The size of the model file
modelVersions.files.pickleScanResult	string	Status of the pickle scan ('Pending', 'Success', 'Danger', 'Error')
modelVersions.files.virusScanResult	string	Status of the virus scan ('Pending', 'Success', 'Danger', 'Error')
modelVersions.files.scannedAt	Date | null	The date in which the file was scanned
modelVersions.files.metadata.fp	enum (fp16, fp32) | undefined	The specified floating point for the file
modelVersions.files.metadata.size	enum (full, pruned) | undefined	The specified model size for the file
modelVersions.files.metadata.format	enum (SafeTensor, PickleTensor, Other) | undefined	The specified model format for the file
modelVersions.images.url	string	The url for the image
modelVersions.images.nsfw	string	Whether or not the image is NSFW (note: if the model is NSFW, treat all images on the model as NSFW)
modelVersions.images.width	number	The original width of the image
modelVersions.images.height	number	The original height of the image
modelVersions.images.hash	string	The blurhash of the image
modelVersions.images.meta	object | null	The generation params of the image

Note: The download url uses a content-disposition header to set the filename correctly. Be sure to enable that header when fetching the download. For example, with wget:

wget https://civitai.com/api/download/models/{modelVersionId} --content-disposition

Example

The following example shows a request to get the first 3 TextualInversion models from our database:

curl https://civitai.com/api/v1/models/1102 \
-H "Content-Type: application/json" \
-X GET

This would yield the following response:

GET /api/v1/models-versions/:modelVersionId

Endpoint URL

https://civitai.com/api/v1/model-versions/:id

Response Fields

Name	Type	Description
id	number	The identifier for the model version
name	string	The name of the model version
description	string	The description of the model version (usually a changelog)
model.name	string	The name of the model
model.type	enum (Checkpoint, TextualInversion, Hypernetwork, AestheticGradient, LORA, Controlnet, Poses)	The model type
model.nsfw	boolean	Whether the model is NSFW or not
model.poi	boolean	Whether the model is of a person of interest or not
model.mode	enum (Archived, TakenDown) | null	The mode in which the model is currently on. If Archived, files field will be empty. If TakenDown, images field will be empty
modelId	number	The identifier for the model
createdAt	Date	The date in which the version was created
downloadUrl	string	The download url to get the model file for this specific version
trainedWords	string[]	The words used to trigger the model
files.sizeKb	number	The size of the model file
files.pickleScanResult	string	Status of the pickle scan ('Pending', 'Success', 'Danger', 'Error')
files.virusScanResult	string	Status of the virus scan ('Pending', 'Success', 'Danger', 'Error')
files.scannedAt	Date | null	The date in which the file was scanned
files.metadata.fp	enum (fp16, fp32) | undefined	The specified floating point for the file
files.metadata.size	enum (full, pruned) | undefined	The specified model size for the file
files.metadata.format	enum (SafeTensor, PickleTensor, Other) | undefined	The specified model format for the file
stats.downloadCount	number	The number of downloads the model has
stats.ratingCount	number	The number of ratings the model has
stats.rating	number	The average rating of the model
images.url	string	The url for the image
images.nsfw	string	Whether or not the image is NSFW (note: if the model is NSFW, treat all images on the model as NSFW)
images.width	number	The original width of the image
images.height	number	The original height of the image
images.hash	string	The blurhash of the image
images.meta	object | null	The generation params of the image

Note: The download url uses a content-disposition header to set the filename correctly. Be sure to enable that header when fetching the download. For example, with wget:

wget https://civitai.com/api/download/models/{modelVersionId} --content-disposition

Example

The following example shows a request to get a model version from our database:

curl https://civitai.com/api/v1/model-versions/1318 \
-H "Content-Type: application/json" \
-X GET

This would yield the following response:

GET /api/v1/models-versions/by-hash/:hash

Endpoint URL

https://civitai.com/api/v1/model-versions/by-hash/:hash

Response Fields

Same as standard model-versions endpoint

Note: We support the following hash algorithms: AutoV1, AutoV2, SHA256, CRC32, and Blake3

Note 2: We are still in the process of hashing older files, so these results are incomplete

GET /api/v1/tags

Endpoint URL

https://civitai.com/api/v1/tags

Query Parameters

Name	Type	Description
limit (OPTIONAL)	number	The number of results to be returned per page. This can be a number between 1 and 200. By default, each page will return 20 results. If set to 0, it'll return all the tags
page (OPTIONAL)	number	The page from which to start fetching tags
query (OPTIONAL)	string	Search query to filter tags by name

Response Fields

Name	Type	Description
name	string	The name of the tag
modelCount	number	The amount of models linked to this tag
link	string	Url to get all models from this tag
metadata.totalItems	string	The total number of items available
metadata.currentPage	string	The the current page you are at
metadata.pageSize	string	The the size of the batch
metadata.totalPages	string	The total number of pages
metadata.nextPage	string	The url to get the next batch of items
metadata.prevPage	string	The url to get the previous batch of items

Example

The following example shows a request to get the first 3 model tags from our database:

curl https://civitai.com/api/v1/tags?limit=3 \
-H "Content-Type: application/json" \
-X GET

This would yield the following response:

{
  "items": [
    {
      "name": "Pepe Larraz",
      "modelCount": 1,
      "link": "https://civitai.com/api/v1/models?tag=Pepe Larraz"
    },
    {
      "name": "comic book",
      "modelCount": 7,
      "link": "https://civitai.com/api/v1/models?tag=comic book"
    },
    {
      "name": "style",
      "modelCount": 91,
      "link": "https://civitai.com/api/v1/models?tag=style"
    }
  ],
  "metadata": {
    "totalItems": 200,
    "currentPage": 1,
    "pageSize": 3,
    "totalPages": 67,
    "nextPage": "https://civitai.com/api/v1/tags?limit=3&page=2"
  }
}