Copy page

Tutorials

Declare AI contribution

Generative AI contribution is declared through a single attribute, ai-contribution. It uses the same name and the same four values on every resource that can carry a declaration, so you only have to learn it once.

The four values

Value	Meaning
undeclared	No declaration has been made. This is the default value.
none	Declared as containing no AI contribution.
partly	AI contributed in part.
entirely	Entirely generated by AI.

undeclared is not none

The distinction is deliberate:

• none means the client declares that no AI was involved.
• undeclared means no declaration has been made. It is the default value, including on your entire catalog predating this feature.

A silence is never turned into a declaration. Do not map missing data in your own system to none — send nothing at all, or send undeclared.

Where to declare it

Four things can carry a declaration, each on its own resource:

What	Resource	Attribute	What the declaration qualifies
Credit	roles	ai-contribution	The degree of AI contribution of that specific credit
Static album cover	products	cover-ai-contribution	The degree of AI contribution of the static cover artwork
Album motion art	asset-attachments	ai-contribution	The degree of AI contribution of the animated artwork
Video	videos	ai-contribution	The degree of AI contribution of the video

Note that products uses cover-ai-contribution, not ai-contribution: the declaration is about the cover artwork specifically, not about the release as a whole.

partly is meaningful on assets, not just on credits

partly is not reserved for credits. It has a real meaning on artwork and video: a photographic cover retouched with generative fill or outpainting is partly, as is a video mixing filmed footage with generated shots.

There is no track-level attribute

A track does not carry a declaration of its own. The track level is derived from its credits. If you are looking for an ai-contribution attribute on the tracks resource, there isn't one by design — declare on the credits instead, via roles.

Write semantics

The same three rules apply on all four resources:

Payload	Effect
Attribute absent	No-op. The current value is left untouched.
"undeclared"	Resets the declaration to "not declared".
"none" / "partly" / "entirely"	Records the declaration.

Declaring

Code
PATCH https://api.idol.io/api/v2/roles/99e73ff1b87f37d1198ed50240796c18f1d2588c
Content-Type: application/vnd.api+json

Code
{
  "data": {
    "type": "roles",
    "id": "99e73ff1b87f37d1198ed50240796c18f1d2588c",
    "attributes": { "ai-contribution": "partly" }
  }
}

The same on a static cover, a motion art and a video:

Code
{
  "data": {
    "type": "products",
    "id": "1",
    "attributes": { "cover-ai-contribution": "entirely" }
  }
}

Code
{
  "data": {
    "type": "asset-attachments",
    "id": "42",
    "attributes": { "ai-contribution": "partly" }
  }
}

Code
{
  "data": {
    "type": "videos",
    "id": "7",
    "attributes": { "ai-contribution": "none" }
  }
}

Leaving a declaration alone

Simply omit the attribute. This payload updates the product name and does not touch the cover declaration:

Code
{
  "data": {
    "type": "products",
    "id": "1",
    "attributes": { "name": "New title" }
  }
}

Clearing a declaration

Send undeclared explicitly:

Code
{
  "data": {
    "type": "products",
    "id": "1",
    "attributes": { "cover-ai-contribution": "undeclared" }
  }
}

Credits are a projection

roles records are recomputed from the product's raw roles every time the product moves to active status, and on every forced role creation. Moving a product back to draft and re-activating it therefore regenerates its credits and clears the declarations they carried.

This is intended behaviour, not a bug. In practice:

• A declaration set through PATCH /roles/:id is not guaranteed to be stable if the product goes back through draft status.
• After a re-activation, the declarations have to be submitted again.
• If your workflow toggles products between draft and active, re-apply the declarations as the last step, after the product is active.

Cover, motion art and video declarations are not affected — they live on their own records and are not regenerated.

Cover and motion art are two independent declarations

Declaring one does not declare the other.

An album whose cover is a normal photograph but whose motion art was generated by AI is declared on the corresponding asset-attachments record, and products.cover-ai-contribution stays untouched. The reverse is equally true.