ai-content-labels
The CLI is scripts/ai-labels.mjs in this skill's folder. Run it with Node 20.9 or newer, using the
absolute path of this folder, or from inside it:
node scripts/ai-labels.mjs <command> [options]In Claude Code ${CLAUDE_SKILL_DIR} points to this folder:
node "${CLAUDE_SKILL_DIR}/scripts/ai-labels.mjs" <command>. Without the folder, or when sharp is
missing, the same CLI runs with no install: npx -y -p github:JK-G/ai-content-labels ai-labels <command>.
decide writes its next command as ai-labels ..., the name the package installs (also as
ai-content-labels); here it means the node line above. If the ai-content-labels MCP server is
connected, the tools label_image, decide_label, render_label, stamp_image, place_label and
eu_icon do the same. help lists every option. Stamping and PNG output need sharp. When doctor reports it
missing, run the install command it prints (it knows whether this skill sits in a clone of the
repository or was copied on its own), or use the npx line above.
When a label is added
Labels are for compliance, not decoration. The tools add an AI label in two cases only:
- Required. The AI Act asks for it: a deep fake, or AI text on a matter of public interest without editorial review. The label is stamped or rendered as below.
- Unsure. A deciding fact is not known. Ask the user the one question. If you cannot ask, or
the user does not know, answer
unsure(--realistic unsure, MCPrealistic: "unsure"; the same for--public-interestand--editorial-review). The label is then added as a precaution, in the same form as a required one, and the result says so (required: "unsure",precaution: true).
Where the label is only voluntary (all facts known, no duty), nothing is stamped or rendered:
label writes no file and decide gives no next step. Add --voluntary (MCP voluntary: true)
only when the user wants voluntary labels too; they then get the smallest form, the EU icon alone.
ai-labels init --voluntary writes that choice into a project's AGENTS.md. Human-made labels
are the user's own claim and are not affected.
An image you generated or edited yourself
You already know it is AI, so run label right after you make it and before you hand it over. It
decides and, when the label is required or unsure, stamps it in one step:
node scripts/ai-labels.mjs label image.png --realistic --description "what it shows"(MCP: label_image with input or input_base64, realistic and description.)
--realistic,--no-realisticor--realistic unsureis required: would the people who see it take it for a genuine photo or event? Answer honestly; a person, product or place that does not exist but plausibly could counts. If you cannot tell, ask the user; if you cannot ask or the user does not know, pass--realistic unsureand the label is added as a precaution. Without any of them,labelasks the same question asdecideand exits with code 2.--modifiedwhen you changed a real photo or a human-made image instead of making it from scratch.- With
--no-realisticthe label is voluntary:labelstamps nothing and writes no file, not even to--out. The result hasstamped: false,output,labelanddisclosurenull, andaltis the description alone. Publish the original.--voluntarystamps it anyway.--only-if-requiredis the default since 0.6.0 and does nothing. --lang plfor a Polish label;--outfor the output path (default<name>.ai-label.<ext>next to the image). Form, size, spot and colour follow the defaults in the next section: add--region(or--region-path) when only part of the image is AI,--avoidfor what the label must not cover, and--color autoor--palettefor a branded graphic.- Then publish the
altit returns, as in step 4 below. For anything else (video, audio, text, an image someone else made, a human-made label) use the full workflow.
The smallest label, in the least invasive spot
Always label in the smallest legible form that fits the case, in the spot where it covers the least, unless the user asks for something else or you have a stated reason. The tools do this by default, so mostly it means: do not override the defaults without a reason.
- Form. Every AI label, required, precautionary or voluntary, is the EU "AI" icon alone by
default (
stamp,labelandplacedo this for you), with the words in the alt text. The Code of Practice asks for the icon with the letters "AI" (Measure 1.1(a)); a word is only encouraged (1.1(b)). Add the word with--short("Generated", "Modified") when the user wants it, or on feed ads (see "Which label"). Human-made labels keep their words, because a hand alone is not a sign people know.--full("Generated with AI") only when the user asks for it. For a deep fake, also put the label sentence in a visible caption. - Size. The automatic size is the smallest legible one where the image is shown 552 CSS px
wide, about the column of a desktop feed (the default the project owner chose): 17 px tall for the
icon, 20 px for a pill (minimal, or with words). There the label carries letters the EU minimum
eyesight for driving can read, and the word is set at 10.5 px or more. A phone that shows the
image full width shows the label about 0.7 as tall; the result says how tall in
label.phoneHeight. Do not pass--heightto make it smaller. - Where it will be shown. Before you stamp or place, know where the image will be published,
from the task or the conversation. Keep the default for feed posts. Pass
--display-width:390when the image is shown only on phones (a story, a reel) or the user wants the label legible on a phone; it makes the label larger in the file.- The width of the column when a page or an app shows the image at a fixed width (a blog
column, a card in a grid).
The platforms do not publish the width they show an image at, and the tool has no presets for
them. Use a width you measured or the user gave you; never pass a width to make the label smaller.
If the user finds the label too big, show them
label.displayHeightandlabel.phoneHeight, and offer the icon form (it is the smallest) before a smaller--height, which makes it harder to read.
- Place. Leave
--positionatauto: the bottom-right corner when it is free, else the freer of bottom centre and bottom left, else the top edge. The result says which spot it took and why (label.reason,label.spots). Set--positiononly when the user asks, or when the platform covers that spot (a story's reply bar at the bottom, for example). - Part of an image. When only one element of a composite is AI (a generated photo inside a
designed ad) and the label should mark that element, pass its box:
--region x,y,width,heightin px or in % of the image (50%,35%,46%,57%). If you composed the graphic you know the box; otherwise estimate it from the image. For a rounded or angled element (a photo in a shield or circle), pass its shape instead of a box:--region-path "M300 200 H780 V800 L540 1000 L300 800 Z"(the clip path in image px, as in your HTML or SVG template) or--region-mask mask.png(its alpha, or its brightness when it has no transparency). The label and its margin then stay inside the shape. The label goes on that element, in its least invasive spot; use--kind generatedfor an element AI made whole. When the element is too small for a legible label, the label goes on the whole image instead and the result haslabel.regionNote: then name the AI element in the alt text or the caption ("The photo of the laptop was generated with AI"). Do not pass--heightto force a smaller label onto the element. - What to keep clear. Look at the image yourself before you stamp or place. The automatic spot
sees only texture, so a smooth back, a face in soft light or a clean product surface can look
free. Pass
--avoid x,y,width,height(px or %, once per box) for faces, people, the product or subject, and text. The result lists every spot that was not taken and why (label.why). If no spot is left, the command stops with the reasons: try the icon form, smaller avoid boxes or a--positionyou checked. - Safe zones. For a story or reel, keep the label out of the platform's buttons and captions
with
--safe-zone.meta-reelsis built in (14% top, 35% bottom, 6% sides, from the Meta Ads Guide for Instagram Reels, checked 2026-10-18); it is not a source for Stories. For any other platform, take the insets from the platform's own template and pass them as--safe-zone top,right,bottom,leftin px or %. Do not guess them. - Colour. The icon is the official EU disc in black or white, whichever stands out more from the
spot, and takes no colour. A label in brand colours is a pill with the word, which a colour gives
you without
--short. When the user or the brand guide gives brand colours for it, pass them:--color #hexfor one, or--palette #hex,#hexto let the tool pick the one that stands out most from the spot (used exactly as given; neutral when none stands out). Without a known brand colour, for a branded graphic such as an ad or a social post, use--color auto: the accent colour of the image, toned to keep 4.5:1 contrast.autoreads the whole image, or with a region the designed part outside it when that part is at least 20% of the image (label.color.sampledsays which). Keep the icon on plain photos.
HTML pages, ad templates and UI
When the label is drawn as HTML or SVG over an image (a landing page hero, an ad rendered from HTML
to PNG, an app card), do not stamp the image. Run place (MCP place_label) on the image as it
will be shown, with the same options you would give stamp:
node scripts/ai-labels.mjs place hero.png --kind generated --media image --region-path "..." --avoid 120,80,300,400 --jsonIt writes nothing and returns box (px), boxPercent (% of the image: left, top, width,
height, right, bottom and anchor) and renderArgs, the render options that draw the
same label. Put the label in the image's container (position: relative) and pin it by the sides
boxPercent.anchor names: a bottom-right label with CSS right and bottom from boxPercent, a
top-left one with left and top, a centre one centred. Then it stays in its corner even when the
drawn label is not exactly box.width wide.
- As SVG:
renderwithrenderArgs, and its width set toboxPercent.width%, so it scales with the image. - As HTML:
render --format htmlwithrenderArgs, but--heightset tolabel.cssHeight: the label's height in CSS px where the image is shown (label.displayWidth; pass--display-widthtoplacewhen the image is shown at another width than the default 552 px). The pill (or the icon) is then exactly that tall. It must be at least 20, 17 for the icon.
Keep the label sentence in the alt text or caption as in step 4.
Workflow
Get the facts, mostly from context. You need the media type (image, video, audio, text) and the origin:
generated(all AI, apart from the prompt),modified(real or human-made content partly changed by AI),assisted(only standard edits such as colour or noise) orhuman. Then:--realisticor--no-realistic: would its audience take it for a genuine photo, recording or event? A person, product or place that does not exist but plausibly could counts; photorealism alone does not decide it. This decides most cases.--creative: an evidently artistic, satirical or fictional work, obvious to its audience. Read strictly: news or a product shot does not count, and an advertisement only in specific cases.- Text only:
--public-interest(published to inform the public on matters of public interest) and--editorial-review(a person with relevant knowledge checked the substance, at least fact-checked it; a spell-check or quick approval does not count; no AI changes after sign-off; and a named person or company holds editorial responsibility).
Ask only for what you cannot infer, in one short question. If
decideanswersUNKNOWN(required: "unknown"over MCP), ask the one question it names inmissing(realistic,public_interestoreditorial_review); never guess it. If you cannot ask, or the user does not know, answerunsure(nextholds that call): the label is then added as a precaution. For public-interest text it always asks about editorial review, because that decides the case.The duty binds deployers in the EU, and deployers elsewhere when they foresee the content being used in the EU, for example by publishing it on the open internet. A person acting in a purely personal, non-professional way has no duty; work for pay or regular economic benefit, as a freelancer or for an employer, is professional. If the user is clearly acting privately, say the duty does not apply to them; add a label only if they want one (
--voluntary).Decide:
decide --media image --origin generated --realistic --lang pl. It says whether the label is a legal duty or a voluntary one, the next command to run, which label to use (and the official EU icon with the same meaning), where to put it, and the label sentence (disclosure).--explainadds the basis, notes and sources;--jsonalways has everything. In JSON and over MCP,nextholds the next call:tool,argumentsto pass unchanged,fill(what you still supply, such asinputanddescription) and the same step as a CLI line (cli). For a voluntary AI labelnextis null and you are done: no label is added unless the user asked for voluntary labels (--voluntary).Make the label:
- Image file:
stamp photo.jpg --kind generated --media image --lang pl --description "...".--kindis required: stamp never guesses the claim it burns in. For an image you made yourself,labeldoes steps 2 and 3 at once. Writesphoto.ai-label.jpgwith the label in the pixels, keeps the EXIF and XMP of the original and adds an IPTC DigitalSourceType to the XMP for generated and modified labels. Form, size, spot and colour follow the defaults above. It stamps one still file per run and refuses to overwrite or to stamp a labelled file again unless you pass--force. - For social posts, crop to the platform's final aspect first (Instagram 4:5 or 1:1), then
stamp, so the label sits inside every crop. For stories and reels add
--safe-zone. The result'slabel.displayHeightsays how tall the label looks on a phone. Awarningin the result means the label had to shrink to fit (a wide banner): tell the user, and use the icon form or a label next to the image. Alabel.regionNotemeans the region was too small, so the label went on the whole image: name the AI part in the alt text or the caption. - A folder of images: run
decideonce per distinct kind of content, then stamp each file with its own--description, and report one table: file, output, alt text. - Web page or app: use
render --format html(real text: zooms, reflows, translates) and put the CSS fromrender --format html --csson the page once. For a label over an image, get the spot and the options fromplacefirst (see "HTML pages, ad templates and UI"). The HTML label follows the page's color-scheme (light unless the page declares light dark); force it with--theme. Use SVG or PNG (render ... --out label.svg) for images, video overlays and places that only accept an image. - Video, for now: render a PNG (
render ... --out label.png --height <about 6% of the shorter side>) and overlay it away from the player controls. The Code of Practice asks for the label at the start, at regular intervals where possible and at least after every break, and encourages keeping it for the whole video. This project recommends the whole video, which is what this does:ffmpeg -i in.mp4 -i label.png -filter_complex "overlay=24:24" -c:a copy out.mp4. Put the label sentence in visible text next to the player and say it in the audio (a spoken disclaimer at the start, or a line in the audio description); captions alone do not reach blind viewers. Labels that change with the timeline are not built yet. - Audio: put the visual label on the player, cover or page, and tell the user to add a short spoken disclaimer at the start, in the language of the recording; in long or live recordings, repeat it at regular intervals where it fits and at least after breaks. Put the sentence at the start of the transcript too. Audio alone cannot carry a visual label.
- Image file:
Publish the alt text and the label sentence with the content. Alt text = a short description of what the image shows, then the label sentence, e.g.
alt="Modern house among pine trees, architectural visualisation. Generated with AI: image."Look at the image and describe what is actually there; do not reuse the example. Pass--descriptionsostampandrenderreturn it composed asalt; without italtis null. Never use the label sentence (disclosure) alone as the alt of an informative image; it is the alt of the label itself, whichrenderreturns aslabelAlt. When the label is a legal duty, also put the sentence in a visible caption. Text burned into pixels is invisible to screen readers. For a separate label on a page:- inline SVG works as is (it carries
role="img",langand anaria-label); prefer--format htmlfor page text that must reflow; - as
<img src="label.svg">, give the img its own alt with the label sentence; - when the content's alt or caption already carries the sentence, give the separate label
alt=""oraria-hidden="true", so screen readers do not hear it twice.
- inline SVG works as is (it carries
Report back in a few lines: what you labelled and where the files are, whether the label is required, precautionary (an
unsureanswer) or voluntary and on what basis, what you left unlabelled because the label was only voluntary, and anything you assumed.
Which label
| Situation | Options |
|---|---|
| All of it made by AI | --kind generated |
| Real or human-made content changed by AI (a swapped face, added objects, a replaced voice) | --kind modified |
| AI was involved and you want your own wording | --kind basic --text "Voice generated with AI" |
| Made by a person, confirmed by the user | --kind human --media text,image. If the person wants to place the label by hand, point them to the ready-made files in labels/human-made of the repository (or the human-made-labels.zip release asset) instead |
| AI image with a human-written text | --kind generated --media image --human text |
| An ad or post in a feed, where the caption may be cut off ("See more") or limited to a short text field | Add --short, so the word is on the image. The label sentence must be seen at first exposure (Code of Practice Sub-measure 1.2.1), and text below the fold is not. Keep the icon alone only when the sentence is in the first visible line of the caption |
| A human-made layout, mockup or collage containing an AI-generated element | Run decide with --realistic for the element. To mark just that element, stamp the whole graphic with --kind generated --media image --region <the element's box>; if the post is about the visualisation, crop to the element and stamp that; to label the design as a whole, use --kind modified --media image with --description naming the AI part |
--medialists only the parts that are AI (or, with--kind human, the parts made by a person). A type cannot be in both--mediaand--human.- Match the language of the content:
--lang plfor Polish. Onlyenandplare built in; for another EU language pass--langwith--textin that language (plain words, no abbreviation other than "AI"), e.g.--lang de --text "Mit KI generiert". The sentence is then your text alone, so name the part in it ("Stimme mit KI generiert"). - Forms (
--form icon|minimal|short|full, or--icon,--minimal,--short,--full): the icon is the default ofstamp,labelandplacefor AI labels;--shortadds one word ("Generated"),--fullthe phrase "Generated with AI".renderkeeps the short form as its default. A pill colour (--color,--palette) and a human-made part need a pill, so they get the short form. --minimaldrops the text but keeps the pill: the author mark (EU "AI" disc, or a hand in the same disc) plus the content-type icons, at least 20 px. Without text, "generated" and "modified" look the same, in the icon and the minimal form alike, so the alt text must carry the difference.- The hand mark is this project's design, not an EU icon. It has no meaning under the AI Act. Where you use it, explain it once (a legend, caption or an "about our labels" page).
- When the user wants to place an AI label by hand, point them to the ready-made files in
labels/ai-generatedof the repository (or theai-generated-labels.ziprelease asset), and say whether the label is required for their content first. - The untouched EU files:
eu generated --variant black --out ai-generated.svg(alsobasic,modified; variantsblack,white,black-transparent,white-transparent).
Do not
- Do not call labelled content "AI Act compliant". Say the label follows the EU icon guidance;
decideis a checklist, not legal advice. - Do not put a human-made label on anything generative AI produced or changed, and do not infer it.
- Do not use the EU transparent variants on top of photos; their letters can drop below WCAG contrast there. Labels drawn by this tool keep 4.5:1 text contrast on any backdrop.
- Do not shrink a stamped label below its automatic size (it is already the smallest legible one), cover it with other UI, animate it (WCAG 2.2.2) or make it flash (WCAG 2.3.1).
- Stamping changes the pixels, so an existing C2PA manifest stops verifying. If the file had one, tell the user to sign it again after stamping.
The rules behind decide, with sources: references/rules.md.