Model version gifts

A creator of a paid or early-access model version can give access away free with gift codes. A code is either a shareable link with an optional expiry and claim cap, or one of a batch of single-use codes. Claiming a code gives the account the same access a purchase would, and no Buzz is charged.

Every endpoint here is authenticated with an API key or OAuth token carrying the ModelsWrite scope, a full-access personal API key, or a signed-in session. Other tokens are refused with 403. Responses are never cached. Creating, minting, revoking and claiming also need an account in good standing with a verified email; otherwise they answer 403.

Codes look like cvg_ followed by 26 characters. Matching ignores case and hyphens.

Claim a gift

POST /api/v1/model-versions/gifts/claim

{ "code": "cvg_…" }

Response

{ "modelVersionId": 555, "modelId": 123, "alreadyHadAccess": false }

alreadyHadAccess: true means the account already had this access (or the version is no longer gated), and the claim was not used up.

Status	When
400	The code is unknown, expired, revoked or used up (one message for all four); the version is not published; or it is your own model.
429	Too many claim attempts. Retry later.

Mint single-use codes

POST /api/v1/model-versions/{id}/gifts

You must own the model (otherwise 403), and the version must be gated (otherwise 400). The same ownership rule applies to creating, listing and revoking.

Field	Type	Description
count	integer, 1–500	How many codes to mint.
expiresAt	ISO date-time, optional	When the codes stop working.
label	string ≤ 100, optional	Your own note, shown in the list.

A version can hold at most 5000 live, unclaimed codes. Minting and link creation are rate-limited per account (429).

Response (201)

{ "batchId": "0b6f6a3e-…", "codes": ["cvg_…", "cvg_…"] }

The codes are returned only here. Civitai stores a fingerprint, not the code, so store them yourself.

Create a gift link

POST /api/v1/model-versions/{id}/gifts/link

Field	Type	Description
maxRedemptions	integer ≥ 1, optional	How many accounts can claim it. Omit for no limit.
expiresAt	ISO date-time, optional	When it stops working.
label	string ≤ 100, optional	Your own note.

Returns 201 with { "id": 42, "code": "cvg_…" }. Share it as https://civitai.com/gift/<code>; any code, single-use ones included, can also be pasted on https://civitai.com/gift.

List gift codes

GET /api/v1/model-versions/{id}/gifts

{
  "links": [
    { "id": 42, "codeHint": "7KQ2", "label": null, "maxRedemptions": 10, "redemptionCount": 3,
      "expiresAt": null, "revokedAt": null, "createdAt": "2026-11-07T12:00:00.000Z" }
  ],
  "batches": [
    { "batchId": "0b6f6a3e-…", "label": "Patreon", "total": 500, "claimed": 120, "live": 380,
      "createdAt": "2026-11-07T12:00:00.000Z", "expiresAt": null }
  ]
}

links holds your gift links and batches one summary per batch of single-use codes, live ones first; live counts codes that are still claimable. Codes themselves are never returned, and neither is who claimed them.

Revoke

DELETE /api/v1/model-versions/{id}/gifts/{giftId}
DELETE /api/v1/model-versions/{id}/gifts/batch/{batchId}

Returns { "revoked": <count> }. A revoked code can no longer be claimed. Accounts that already claimed keep their access. Revoking a code that is already revoked, or that does not exist, answers 404.