update_subject

Update a subject

Change what a subject is or how it is described, bind the voice it speaks in, and push a new identity image onto it. canonical makes that image the one that travels — this is how a subject gets stronger with use: generate, promote the best result, and the next generation is better.

Scope

generation.write — Makes, edits, imports, shares and deletes media in the account.

Behaviour

Writes: Creates or changes items in the caller's own account.
Can delete or overwrite: Can delete, overwrite, cancel or withdraw something the caller already has, so a host should confirm it.
Stays in the account: Stays inside the caller's private Kuro account: any media provider it calls acts on Kuro's account, and the result is visible to no one else.
Idempotent: Calling it again with the same arguments has no further effect.

Inputs

subject_idstring · required
uuid
namestring · optional
at least 1 character · at most 60 characters
kindstring · optional
one of "character", "location", "product", "prop", "wardrobe"
descriptionstring or null · optional
prompt_fragmentstring or null · optional
The words that travel into every prompt this subject is tagged into. Null clears them.
avatarobject (type: "upload") or object (type: "generation") or null · optional
The small round one — a shelf, a rail, a tag. Null takes it off.
coverobject (type: "upload") or object (type: "generation") or null · optional
The wide one, behind the name on its card. Null takes it off.
sheetobject (type: "upload") or object (type: "generation") or null · optional
A character sheet for a person to read: hero pose, turnaround, palette. Held for a reader and never seated as a model reference — seating a collage teaches the model to render the collage. Null takes it off.
voiceobject or null · optional
The voice this subject speaks in — cast_voice reads a portrait and returns ids to choose from. Null unbinds it.
tagsarray of string · optional
The same tags the account puts on its work, so one tag can group a client's people and products beside what was made of them. Replaces the whole list — send the tags it should end up with.
at most 8 items
favoriteboolean · optional
add_identityobject (type: "upload") or object (type: "generation") · optional
canonicalboolean · optional
True promotes `add_identity` to the face that travels.
remove_identitystring · optional
A media object id from the subject's identity strip (get it from list_subjects), taken off the strip.
uuid

Example call

A tools/call request with the required arguments only, each a placeholder read off the schema. Replace them before sending.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_subject",
    "arguments": {
      "subject_id": "00000000-0000-4000-8000-000000000000"
    }
  }
}

Input schema

As the server sends it in tools/list.

{
  "type": "object",
  "properties": {
    "subject_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "kind": {
      "type": "string",
      "enum": [
        "character",
        "location",
        "product",
        "prop",
        "wardrobe"
      ]
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 300
        },
        {
          "type": "null"
        }
      ]
    },
    "prompt_fragment": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 600
        },
        {
          "type": "null"
        }
      ],
      "description": "The words that travel into every prompt this subject is tagged into. Null clears them."
    },
    "avatar": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "const": "upload"
                },
                "upload_id": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "required": [
                "type",
                "upload_id"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "const": "generation"
                },
                "generation_id": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "required": [
                "type",
                "generation_id"
              ],
              "additionalProperties": false
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "The small round one — a shelf, a rail, a tag. Null takes it off."
    },
    "cover": {
      "anyOf": [
        {
          "$ref": "#/properties/avatar/anyOf/0"
        },
        {
          "type": "null"
        }
      ],
      "description": "The wide one, behind the name on its card. Null takes it off."
    },
    "sheet": {
      "anyOf": [
        {
          "$ref": "#/properties/avatar/anyOf/0"
        },
        {
          "type": "null"
        }
      ],
      "description": "A character sheet for a person to read: hero pose, turnaround, palette. Held for a reader and never seated as a model reference — seating a collage teaches the model to render the collage. Null takes it off."
    },
    "voice": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "model": {
              "type": "string",
              "enum": [
                "elevenlabs-tts",
                "eleven-v4",
                "gemini-3.1-flash-tts",
                "kokoro-82m",
                "minimax-speech-2.8-hd",
                "inworld-tts-2"
              ],
              "description": "The TTS model this voice belongs to."
            },
            "voice_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120,
              "description": "A voice this model offers — cast_voice returns them best-first for a face, and list_models carries each model's roster."
            },
            "style_preset": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "warm_narrator",
                    "upbeat_promo",
                    "calm_close",
                    "movie_trailer"
                  ]
                },
                {
                  "type": "null"
                }
              ],
              "description": "How it is delivered. Omit for the model's own plain read."
            },
            "language_code": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 2,
                  "maxLength": 35
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "model",
            "voice_id"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The voice this subject speaks in — cast_voice reads a portrait and returns ids to choose from. Null unbinds it."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40
      },
      "maxItems": 8,
      "description": "The same tags the account puts on its work, so one tag can group a client's people and products beside what was made of them. Replaces the whole list — send the tags it should end up with."
    },
    "favorite": {
      "type": "boolean"
    },
    "add_identity": {
      "$ref": "#/properties/avatar/anyOf/0",
      "description": "A generation or upload to add to the identity strip."
    },
    "canonical": {
      "type": "boolean",
      "description": "True promotes `add_identity` to the face that travels."
    },
    "remove_identity": {
      "type": "string",
      "format": "uuid",
      "description": "A media object id from the subject's identity strip (get it from list_subjects), taken off the strip."
    }
  },
  "required": [
    "subject_id"
  ],
  "additionalProperties": false
}

Related tools

generate_image
Make an image in the user's Kuro account.
generate_clip
Start a short video clip generation.
animate_image
Animate an existing image or upload into a clip.
generate_voiceover
Start a voice-over generation from text.
generate_music
Start a music generation from a creative brief.
set_recipe_gallery
Put a ready generation made with a recipe on that recipe's public gallery — the examples a reader sees under the recipe — or take it off with `listed: fal…
quote_generation
Price a request exactly, and compare it to the balance, without creating anything.
set_brand_note
Replace the user's brand note (at most 2000 characters): who they are, what they sell, their tone, colours and words to avoid.

Every tool· This page as Markdown