---
name: depicta
version: "1.5.0"
description: >
  This skill should be used when the user asks to "generate an image",
  "create a photo", "make an illustration", "design an icon", "draw a
  diagram", "edit this image", "remove the background", "resize an image",
  "create a logo", "make a comic", "create a storyboard", "create a product
  photo", "restore a photo", "combine images", "add a watermark", or any
  request involving image generation, editing, processing, diagrams,
  graphics, visual stories, or visual content of any kind. Supports CLI
  and REST API.
---

# Depicta — Image Generation & Editing

Generate, edit, and process images via the Depicta CLI or REST API.

## Set up Depicta

Do this when the user asks you to set up Depicta, or when a command says it is not signed in. Steps 3 and 4 are the user's: you cannot do them, and you never see the key.

1. **Check for Node.js or Python.** Run `node --version` (18 or later) or `python3 --version` (3.10 or later; `uvx` comes with uv). One is enough: the CLI runs with `npx depicta@latest` or `uvx depicta@latest`, with no install. If neither is there, ask the user to install Node.js from https://nodejs.org.
2. **Install this skill**, so it loads in later sessions:
   ```bash
   mkdir -p ~/.claude/skills/depicta/references
   curl -fsSL https://depicta.ai/SKILL.md -o ~/.claude/skills/depicta/SKILL.md
   for f in api-examples cli-commands printing story-mode; do
     curl -fsSL "https://depicta.ai/skill/$f.md" -o ~/.claude/skills/depicta/references/$f.md
   done
   ```
3. **An account and an API key.** Ask the user to sign up at https://depicta.ai and create an API key in the dashboard (https://depicta.ai/dashboard). Never ask the user to paste the key into this chat, and never write it into a file yourself.
4. **Store the key.** Ask the user to run `npx depicta@latest auth login` in their own terminal, not through you, and paste the key at its prompt. Or they can set `DEPICTA_API_KEY` in their shell profile or in Claude Code's settings (`"env"` in `~/.claude/settings.json`), then restart Claude Code.
5. **Check that it works:** `npx depicta@latest balance` shows the credit balance and costs nothing. A 401 means the key is missing or wrong: go back to step 4.
6. Then use the rest of this skill.

## Getting Started

Where you can run commands (Claude Code, a terminal), use the CLI even when the Depicta connector is connected. Use the connector's tools only where the CLI cannot run (Claude Desktop, claude.ai chat).

The CLI runs via `npx` (Node.js) or `uvx` (Python). No global install needed. Use `@latest` to avoid stale cached versions:

```bash
npx depicta@latest    # Node.js
uvx depicta@latest    # Python
```

**Authenticate once** — credentials are stored in `~/.config/depicta/config.json`. Do NOT prefix every command with `DEPICTA_API_KEY=...`.

```bash
# If DEPICTA_API_KEY is set
echo $DEPICTA_API_KEY | npx depicta@latest auth login

# Or interactively
npx depicta@latest auth login
```

**Key problems.** If a command returns 401/unauthorized, the key is missing, expired or wrong — do NOT retry or guess. Ask the user to create a new key in the dashboard and store it again (Set up Depicta, step 4).

**Full command reference:** `npx depicta@latest docs`

**API fallback** (non-Node/Python environments): see `references/api-examples.md` or `GET https://api.depicta.ai/v1/openapi.json`. Base URL: `https://api.depicta.ai`. Header: `Authorization: Bearer $DEPICTA_API_KEY`.

## Workflow

For every image task:

1. **Search guidelines** — `npx depicta@latest guidelines search "<use case>"` returns best practices, model picks, prompt patterns, and pitfalls specific to the task. Always search first.
2. **Pick a model** from the Available Models table below. Only use exact aliases — do not guess.
3. **Use reference images** (`-r <path>:<description>`) for consistency across a series. Generate the first image, then reference it on subsequent generations to anchor style, palette, lighting, or layout.
4. **Generate, edit, or combine** using the CLI. Type-specific ops matter: `edit image` vs `edit graphic` vs `edit diagram`.
5. **Post-process** with low-cost processing operations (crop, resize, convert, optimize) for delivery formats. Every processing input is checked by the content classifier first, like an edit input: a rejected image returns `content_rejected` (451) and nothing is charged. Like a generation, every processing response reports what it charged (`cost_eur`) and the balance left (`balance_eur`).

**Timing:** generations typically take 60-120 seconds, sometimes up to 5 minutes. Gateway ceiling is 12 minutes. Set HTTP client timeout to **≥15 minutes** if calling the API directly. Never retry an in-flight request — it double-charges.

**Story generation is async** — see `references/story-mode.md` for the full workflow (characters, locations, polling). When the service is busy a story can wait up to 30 minutes in `processing`, with 0 scenes done, before it starts. If the CLI or your polling times out, the story is still running and will be charged: check it with `depicta story status <id>`, and never resubmit the same storyboard (both would run and be charged). Character names and location names are short labels (up to 60 characters: letters, digits, spaces and `- _ ' . ,`); `style` is at most 200 characters. Every text field of a story is checked by the content classifier. A scene's own `aspect_ratio`, `location` or `characters`, and character `states`, are not supported yet: a story that sets one is refused (422 `validation_error`) before anything is charged; put those details in the scene prompt.

## Available Models

**IMPORTANT: Only use the exact aliases listed.** Do not invent or guess model names. Run `npx depicta@latest models` for current pricing.

| Alias | Model | Tier | Edit | Combine | Story | Best for |
|-------|-------|------|------|---------|-------|----------|
| `mai-fast` | MAI-Image-2.6 Flash | Budget | Yes (1 image) | No | No | **Default for new images** — strong all-round, about 10 s |
| `mai` | MAI-Image-2.6 | Standard | Yes (1 image) | No | No | **Graphics and diagrams** — best in-image text and logos |
| `gemini` | Gemini 3.1 Flash Image | Standard | Yes | Yes (5) | Yes | **Every edit, combine and story**; the only model with 4K |
| `gemini-pro` | Gemini 3 Pro Image | Premium | Yes | Yes (5) | Yes | Premium edits, most consistent relighting |
| `gemini-fast` | Gemini 3.1 Flash Lite Image | Standard | Yes | Yes (5) | No | Cheap drafts and simple combines; weak at small text |
| `seedream` | Seedream 5 Pro | Premium | Yes | Yes (5) | No | Named only: premium editorial images; slow (about a minute), 2K only; processed in Malaysia by a ByteDance company; filtered content kept up to 180 days |
| `gpt-image` | GPT Image 2.5 Flare | Budget | Yes | Yes (5) | No | Named only: infographics, icon sets, exact text. OpenAI keeps inputs for up to 30 days, or longer where the law requires; avoid for photos of people. |
| `gpt-image-pro` | GPT Image 2.5 Sunburst | Budget | Yes | Yes (5) | No | Named only: photorealism; not for dense infographics. OpenAI keeps inputs for up to 30 days, or longer where the law requires; avoid for photos of people. |

Pass the alias exactly as listed: `-m gemini` (not `gemini-3.1`), `-m mai-fast` (not `mai-2.6-flash`). `-m` is optional: without it, the user's default model is used if it can do the operation, otherwise the recommended model for that operation (the bold defaults above). The response names the model used. Pass `-m` when the image suits a specific model, choosing among `mai`, `mai-fast` and the Gemini models. Use `gpt-image` or `gpt-image-pro` only when the user names them (OpenAI keeps inputs for up to 30 days, or longer where the law requires; avoid for photos of people.), and `seedream` likewise (processed in Malaysia by a ByteDance company; filtered content kept up to 180 days).

## Combine & Edit Capacity

Combine takes 2–5 input images, and any request may add up to 5 `-r` references. Some models accept fewer images in total (inputs plus references):

| Alias | Images per request | Notes |
|---|---|---|
| `gemini`, `gemini-pro`, `gemini-fast`; named only: `seedream` (processed in Malaysia by a ByteDance company; filtered content kept up to 180 days), `gpt-image`, `gpt-image-pro` (OpenAI keeps inputs for up to 30 days, or longer where the law requires; avoid for photos of people.) | API limits | Number the inputs and give each one a role in the prompt |
| `mai`, `mai-fast` | **1** | Edit the source image with no extra references; cannot combine |

Exceeding a model's cap returns 422 `validation_error` before any upstream call (`reference_images` or `input_image_urls` names the cap). No credit is charged. Every input or reference image adds to the price (`approximate_cost_eur_per_input_image` in `GET /v1/models`), most on `mai`, `gpt-image` and `gpt-image-pro` (OpenAI keeps inputs for up to 30 days, or longer where the law requires; avoid for photos of people.).

## Critical Rules

**Type-specific edit and combine.** Match the operation to the content type — mismatches degrade quality:
- `edit image` / `combine image` — photos, illustrations, photorealistic work
- `edit graphic` / `combine graphic` — icons, logos, flat/vector assets
- `edit diagram` / `combine diagram` — technical diagrams (pass `-t <type>` for flowchart, sequence, architecture, etc.)

**Reference images for consistency.** `-r <path>:<description>` is the single most effective technique for visual cohesion across a series. Generate the first image, then pass it as a reference on every subsequent generation. The description field tells the model WHAT to use from the reference ("match this lighting and palette", "same line weight and style"). Repeat up to 5 times. Works on generate, edit, and combine commands.

**Positive framing.** Describe what you want, never what to avoid. "No text" can produce text. Say "clean composition without signage" or just don't mention text at all. This is the #1 prompt mistake. The one exception: after the exact text you want, add "no other text" — `mai` and `gemini` may otherwise add text you did not ask for.

**Delivery format matters.** Default to **WebP** (web) or **JPEG** (email, presentations), converted with Depicta's `process convert` and resized with `process resize`, not a local tool, so the Content Credentials survive. For a lighter JPEG or WebP, give convert a lower `quality` (80 to 100, default 93); it stops at 80 so the watermark stays readable. Deliver PNG only when you need transparency (logos, icons) or plan to edit further. A PNG-based PowerPoint deck can hit 100 MB; the same deck as JPEG is under 5 MB with no visible quality loss. **For print** (flyer, menu, poster, ad), keep PNG if the layout tool accepts it, and follow `references/printing.md`: page size and 300 ppi, the 4K pass, crop ratio, real type for small text, and the checklist.

**Keep the AI marking, and label realistic images when they are published.** Every image Depicta generates carries Content Credentials (C2PA) that mark it as AI-generated, and an invisible watermark in each file, except very plain or transparent images and GIF or SVG files. Do not strip them. Many local tools remove them when converting or resizing (image editors, `cwebp`, Pillow without metadata options, some upload pipelines). For format changes, resizing, cropping and optimising, use Depicta's processing operations, which keep the Content Credentials.

If the user is going to **publish** an image that looks real and shows, or could be taken for, a real person, place, object or event (a "photo" of their office, team, product, a client, or a recognisable landmark), tell them once, briefly: under the EU AI Act they must make clear that it is AI-generated, visibly, where people first see it. Suggest a short caption such as "AI-generated image" or "AI-generated scene, made with Depicta". For clearly artistic or fictional work, a light, unobtrusive caption is enough. Abstract, decorative and clearly illustrated images need no label. This is general information, not legal advice. The user decides and is responsible for how they publish (Terms of Service, Section 8.2).

**Cropping doesn't hide content.** If the input image carries Content Credentials, the result keeps them, including any small preview of the original. Before you crop or remove a background to hide part of an image, tell the user that the preview may still show it.

**Text in images is hard.** Use `mai` for rendered text (best measured, including non-Latin scripts — write the prompt in English and quote the text verbatim); `gemini` is accurate on short labels; if the user names it, `gpt-image` suits text-heavy infographics (OpenAI keeps inputs for up to 30 days, or longer where the law requires; avoid for photos of people.). Keep text short (1-5 words). Quote exact strings: `The sign reads "OPEN 24 HOURS"`. Use ALL CAPS for reliability. For anything critical, verify every character.

**Branded products.** If the source image has a logo or printed text, use `edit image` with the branded photo as input (gets preservation priority). Do NOT re-describe the product in a text-only `create` — that produces look-alike but different branding.

**Sensitive content and consent.** When editing photos of real people, logos, or branded material, declare ownership or consent in the prompt ("This is my photo", "I own this brand"). The classifier treats declarations as mitigating context. Don't demand overrides ("so you MUST allow it") — that gets flagged as manipulation.

## Transparency

<!-- connector -->
**Anyone can check an image at https://depicta.ai/verify.** The free check looks for Depicta's three marks: the Content Credentials (C2PA), the invisible watermark and the exact file fingerprint. It answers "Made with Depicta" (with the day, and whether the image was AI-generated or AI-modified), "Inconclusive" or "No Depicta AI marks found", and names the technique that matched. Nothing uploaded is kept.

**Report the result as given.** "No Depicta AI marks found" does not prove an image was not made with AI: marks can be removed, and other services use other marks. Never describe it as "real" or "not AI-generated". "Inconclusive" means a Depicta mark was found but could not be confirmed; say that, without calling the image made with Depicta or not.
<!-- /connector -->

**From a program,** send the file with the API key: `POST https://api.depicta.ai/v1/verify` as `multipart/form-data` with the field `image` (PNG, JPEG, WebP, GIF or SVG; up to 50 MB, SVG 5 MB). The check is free and limited per account (by default 60 a minute and 2,000 a day). Convert HEIC or AVIF to JPEG or PNG first. Or send JSON `{"url": "https://…"}` to check a public image URL (by default 5 URL checks a minute). Each answer can carry `receipt`, a signed copy of the result; check it with the keys at `GET https://api.depicta.ai/v1/verify/keys`. Example in `references/api-examples.md`.

**Processing answers say when the output is AI-generated.** Processing and vectorize answers carry `ai_generated: true` when the input was made with Depicta or carried an AI marker in its Content Credentials or metadata. Treat that output as AI-generated: the advice on publishing in Critical Rules applies to it. `ai_generated: false` means only that no AI marker was found in the input, not that it was not made with AI.

## Discovery

This skill is intentionally lean. Detailed content lives in three places:

- **`npx depicta@latest guidelines search "<topic>"`** — per-use-case best practices (product catalog, children's book, hero image, logo concept, and 80+ more). Tagged by use case, operation, and technique. The FTS index returns up to 5 relevant guidelines per query. **Always search before generating.**
- **`npx depicta@latest docs`** — live command reference with current flags, defaults, and examples.
- **`GET https://api.depicta.ai/v1/openapi.json`** — authoritative API spec (no auth required).
- **`GET https://api.depicta.ai/v1/models`** — current models and prices, in credits (EUR, excluding VAT; VAT is added when you buy credits). Cost depends on the request: `approximate_cost_eur_by_size` gives the price per `image_size` (4K costs about twice 1K), and `approximate_cost_eur_per_input_image` is added for each input or reference image. Prices include the content check every generation goes through and, for every generation but a story for now, the check of the generated image before it is delivered.
- **`GET https://api.depicta.ai/v1/pricing`** — prices per model and operation (a model used only when the user names it comes last, with its rule in `note`), every processing operation with its fixed price, the model each task uses by default (`defaults`), and `charging_rate_eur_per_usd`: the exchange rate (EUR per USD) at which the next generation's OpenRouter costs, billed in USD, are converted to EUR before the pricing factor. It changes as Depicta's OpenRouter credit purchases are used up.
- **`POST https://api.depicta.ai/v1/upload`** — uploads a picture for use as an input (the CLI does it for local files). Its optional `upload_code` field is for Depicta's own upload page; leave it out.

**Bundled references** (in this skill package):
- **`references/cli-commands.md`** — cached CLI reference with command tables, flags, and examples
- **`references/api-examples.md`** — raw HTTP examples for all 9 sync endpoints + reference images + error codes
- **`references/story-mode.md`** — multi-scene story workflow, characters, locations, async polling
- **`references/printing.md`** — print how-to: sizes and resolution, crop, PNG first, real type for small text, prepress checklist

## Error Handling

| Code | HTTP | Meaning |
|---|---|---|
| `credit_insufficient_balance` | 402 | Not enough credits — top up |
| `auth_session_required` | 403 | The action needs the user's dashboard session (API keys, billing, settings, data export, account closure); an API key cannot do it. Do not retry — ask the user to do it at https://depicta.ai/dashboard |
| `auth_account_suspended` | 403 | The account is suspended; no image call works. Do not retry — tell the user. They can still sign in to the dashboard for billing, withdrawals, data export, closure and revoking API keys, or write to hello@depicta.ai |
| `generation_paused` | 403 | Image generation is paused on the account while a person reviews recent requests, usually within one business day. The account, credits and payments are not affected. Do not retry — tell the user; they can write to hello@depicta.ai |
| `model_restricted` | 402 | Low balance — only budget models available |
| `model_not_allowed` | 403 | Model is outside the user's `allowed_models` preference — pick an allowed model or ask the user to change it |
| `model_not_capable` | 422 | Model does not support this operation (e.g., only `gemini` and `gemini-pro` can story) |
| `input_image_unreachable` | 422 | An input or reference image could not be downloaded. The message names the field (e.g. `input_image_urls[1]`, or a story's `characters[0].reference_url`) and the reason: `blocked_address` (private or internal address), `http_status` (e.g. 403 expired link, 404 deleted), `timeout`, `too_large` (over 50 MB, or a request's images over 100 MB together), `not_an_image` (not PNG, JPEG, WebP or GIF) or `connection_failed`. **Not retryable as-is**: use a public, unexpired URL, or pass a local file path so the CLI uploads it. No credit is charged |
| `validation_error` (input image) | 422 | An input image could not be used. The message says which: "An input image could not be read. Send a PNG, JPEG, WebP or GIF file." (a damaged file, or another format), "An input image is too large: the limit is 40 megapixels.", "An input image is too narrow or too wide: the limit is 4:1.", "Animated images are not supported. Send a single still image.", "An input image cannot be checked in this encoding. Re-save it as a baseline JPEG or a PNG.", or "The input images are too large to check together." (up to 10 images are always checked together). `details` names the field when one image is at fault. **Not retryable as-is**: re-save the image as a still PNG or baseline JPEG, crop or shrink it, or send fewer images. No credit is charged |
| `content_rejected` | 451 | Content policy violation — see `tech-rights-declaration` guideline |
| `model_content_rejected` | 451 | The model returned no image for this request (its own filter, or a reply without an image, which can happen with a harmless prompt). Nothing is charged. Retry once or choose another model; rephrasing may help |
| `output_withheld` | 451 | Depicta checked the generated image before delivering it and withheld it: it was not stored or delivered, and nothing is charged. Do not retry the same request unchanged; tell the user the image was withheld and let them change the request. The message never says why |
| `rate_limit_exceeded` | 429 | Too many requests at once — wait the number of seconds in the `Retry-After` response header, then retry (the CLIs retry on their own, a few times). Per account at once: 10 generations, 5 processing requests, 3 uploads (every `-r` or local input image uploads first, so run at most 3 such commands in parallel), 3 stories in progress (wait for one to complete or fail). Never charged |
| `upstream_error` | 502 | The upstream model rejected the request (e.g., context length exceeded, too many input images). **Preferred preflight**: for known-capped models, the API returns 422 `validation_error` with `input_image_urls` naming the model and its cap before calling the upstream; a 502 here means the model's limit was not known at build time or has tightened upstream. **Not retryable as-is** — downscaling images does NOT help for token-limit errors; the tokenizer rescales internally. Reduce **image count** (`mai` and `mai-fast` accept one image) or switch model (`gemini` accepts five). See the Combine & Edit Capacity section. |
| `classifier_unavailable` | 503 | The content check (of the request, or of the generated image) is temporarily unavailable, so nothing was delivered and nothing is charged — retry with backoff |
| `service_unavailable` | 503 | Temporary outage, or the chosen model is temporarily unavailable — retry with backoff or switch model |

On error, inform the user clearly about the cause and suggest next steps. For `upstream_error`, do NOT retry with the same inputs; the error details include the upstream provider's message which tells you exactly what to adjust.

## Version

Skill version: 1.5.0

Check for updates:
```
GET https://api.depicta.ai/v1/skill-version
```
If the version is newer than this file's, repeat Set up Depicta, step 2.