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.nextPageto 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"
}
}