Civitai API

Use this skill to work with Civitai from the local workspace without re-deriving endpoints and auth each time.

Quick start

Store the token in the workspace .env file as:

CIVITAI_API_KEY=...

Use the bundled script:

python .\skills\civitai-api\scripts\civitai.py models --query "flux lora" --limit 5
python .\skills\civitai-api\scripts\civitai.py model 12345
python .\skills\civitai-api\scripts\civitai.py version 67890
python .\skills\civitai-api\scripts\civitai.py by-hash SHA256_OR_AUTOV2_HASH
python .\skills\civitai-api\scripts\civitai.py creators --query "someuser"
python .\skills\civitai-api\scripts\civitai.py tags --query anime
python .\skills\civitai-api\scripts\civitai.py images --model-id 12345 --limit 10
python .\skills\civitai-api\scripts\civitai.py download-url 67890

Workflow

1. Find the thing

When the user has a vague name or concept, start with:

python .\skills\civitai-api\scripts\civitai.py models --query "search text" --limit 10

Useful optional filters include --types, --tag, --username, --sort, --period, --cursor, and --nsfw true|false.

2. Expand the record

Once you have a model id, inspect the full model payload:

python .\skills\civitai-api\scripts\civitai.py model \x3CmodelId>

Use this to pull:

• version ids
• files and hashes
• tags
• creator info
• images
• download URLs already present in the payload

3. Inspect a specific version

When the user already knows the version id, or you need file-level details:

python .\skills\civitai-api\scripts\civitai.py version \x3CmodelVersionId>

4. Reverse-lookup by hash

When the user has a local file hash and wants to identify it:

python .\skills\civitai-api\scripts\civitai.py by-hash \x3Chash>

5. Build a direct download URL

When the user wants an authenticated download URL, build it with:

python .\skills\civitai-api\scripts\civitai.py download-url \x3CmodelVersionId>

Optional download selectors:

• --type
• --format
• --size
• --fp

Use the generated URL directly in a browser or another download tool. Treat the resulting URL as sensitive because it may include ?token=....

Pagination note

Civitai search endpoints may use cursor-based pagination. When the response includes metadata.nextCursor, pass that value back with --cursor instead of forcing --page on search queries.

Auth rules

• Prefer Authorization: Bearer \x3Ctoken> for JSON API calls.
• Use ?token=\x3Ctoken> only for direct download URLs.
• Keep tokens in .env, not in the skill files.

References

Read references/api-notes.md when you need a compact reminder of endpoints, auth, filters, and workflow hints.