openapi: 3.2.0
info:
  title: Civitai Site Model Versions API
  version: '1.0'
  description: 'Browse and search the Civitai public catalog of Stable Diffusion, SDXL, Flux, and video models.

    Exposes models, model versions, images, creators, tags, users, permissions, and the user vault.

    Public read endpoints are cached; authenticated endpoints are not. Authenticate with a personal

    API key issued at civitai.com using a Bearer token.'
  contact:
    name: Civitai Developer Support
    url: https://developer.civitai.com/
  termsOfService: https://civitai.com/content/tos
  license:
    name: Civitai Terms of Service
    url: https://civitai.com/content/tos
servers:
- url: https://civitai.com/api/v1
  description: Civitai Site API
security:
- BearerAuth: []
- {}
tags:
- name: Model Versions
  description: Specific versions of a model with files, hashes, and AIR identifiers.
paths:
  /model-versions/{id}:
    get:
      operationId: getModelVersion
      summary: Get Model Version
      tags:
      - Model Versions
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Model version detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelVersion'
        '404':
          $ref: '#/components/responses/NotFound'
  /model-versions/mini/{id}:
    get:
      operationId: getModelVersionMini
      summary: Get Model Version Mini
      tags:
      - Model Versions
      description: Lightweight model-version payload optimized for client tools.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Lightweight model version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelVersionMini'
  /model-versions/by-hash/{hash}:
    get:
      operationId: getModelVersionByHash
      summary: Get Model Version By Hash
      tags:
      - Model Versions
      parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
        description: AutoV1, AutoV2, SHA256, CRC32, or Blake3 hash of the model file.
      responses:
        '200':
          description: Model version matching the file hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelVersion'
        '404':
          $ref: '#/components/responses/NotFound'
  /model-versions/by-hash:
    post:
      operationId: getModelVersionsByHashes
      summary: Get Model Versions By Hashes
      tags:
      - Model Versions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Map of hash to model version.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ModelVersion'
  /model-versions/by-hash/ids:
    post:
      operationId: getModelVersionIdsByHashes
      summary: Get Model Version IDs By Hashes
      tags:
      - Model Versions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Map of hash to model version ID.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
    ModelFile:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        sizeKB:
          type: number
        type:
          type: string
          enum:
          - Model
          - VAE
          - Config
          - Negative
          - Training Data
          - Archive
          - Other
        format:
          type: string
          enum:
          - SafeTensor
          - PickleTensor
          - Other
        pickleScanResult:
          type: string
        virusScanResult:
          type: string
        scannedAt:
          type: string
          format: date-time
        downloadUrl:
          type: string
          format: uri
        hashes:
          type: object
          properties:
            AutoV1:
              type: string
            AutoV2:
              type: string
            SHA256:
              type: string
            CRC32:
              type: string
            Blake3:
              type: string
    ModelVersionMini:
      type: object
      properties:
        id:
          type: integer
        modelId:
          type: integer
        name:
          type: string
        baseModel:
          type: string
        air:
          type: string
        downloadUrl:
          type: string
          format: uri
    ModelVersion:
      type: object
      properties:
        id:
          type: integer
        modelId:
          type: integer
        name:
          type: string
        baseModel:
          type: string
          description: e.g. SD 1.5, SDXL 1.0, Flux.1 D
        baseModelType:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        publishedAt:
          type: string
          format: date-time
        trainedWords:
          type: array
          items:
            type: string
        air:
          type: string
          description: AI Resource Identifier, e.g. urn:air:sdxl:lora:civitai:12345@67890
        downloadUrl:
          type: string
          format: uri
        files:
          type: array
          items:
            $ref: '#/components/schemas/ModelFile'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        stats:
          $ref: '#/components/schemas/Stats'
    Image:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
          format: uri
        hash:
          type: string
        width:
          type: integer
        height:
          type: integer
        nsfwLevel:
          type: integer
        nsfw:
          type: boolean
        createdAt:
          type: string
          format: date-time
        postId:
          type: integer
        stats:
          $ref: '#/components/schemas/Stats'
        meta:
          type: object
          additionalProperties: true
        username:
          type: string
    Stats:
      type: object
      properties:
        downloadCount:
          type: integer
        favoriteCount:
          type: integer
        commentCount:
          type: integer
        ratingCount:
          type: integer
        rating:
          type: number
        thumbsUpCount:
          type: integer
        thumbsDownCount:
          type: integer
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: Personal API token issued at https://civitai.com/user/account.