create_subject

Create a subject

Name an identity so it can be reused. Offer one when something the user brought appears in a second generation, never unasked, and write into its description what it lacks as well as what it has ("no mouth, only a stitched black nose"). Only for people the user has the right to depict; a real person needs their consent. Pass identity images — a generation you just made, or an upload — and every later generation tagged with this subject gets that face without you finding the file again. A subject with no images still travels as its name and description.

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.
Adds or updates: Adds or updates; nothing the caller already has is deleted or overwritten.
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

namestring · required
at least 1 character · at most 60 characters
kindstring · required
one of "character", "location", "product", "prop", "wardrobe"
descriptionstring · optional
at most 300 characters
prompt_fragmentstring · optional
The words that travel into every prompt this subject is tagged into. The caller's own prompt is never rewritten — only what the provider receives.
at most 600 characters
identityarray of object (type: "upload") or object (type: "generation") · optional
The face that travels, as references. The first is canonical: it is the one a model is shown.
at most 8 items
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 · optional
A voice to bind, so tagging this subject into a voice-over arms the audio seat as well as the face.
fields: model, voice_id, style_preset, language_code
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

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": "create_subject",
    "arguments": {
      "name": "<name>",
      "kind": "character"
    }
  }
}

Input schema

As the server sends it in tools/list.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "kind": {
      "type": "string",
      "enum": [
        "character",
        "location",
        "product",
        "prop",
        "wardrobe"
      ]
    },
    "description": {
      "type": "string",
      "maxLength": 300
    },
    "prompt_fragment": {
      "type": "string",
      "maxLength": 600,
      "description": "The words that travel into every prompt this subject is tagged into. The caller's own prompt is never rewritten — only what the provider receives."
    },
    "identity": {
      "type": "array",
      "items": {
        "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
          }
        ]
      },
      "maxItems": 8,
      "description": "The face that travels, as references. The first is canonical: it is the one a model is shown."
    },
    "avatar": {
      "anyOf": [
        {
          "$ref": "#/properties/identity/items"
        },
        {
          "type": "null"
        }
      ],
      "description": "The small round one — a shelf, a rail, a tag. Null takes it off."
    },
    "cover": {
      "anyOf": [
        {
          "$ref": "#/properties/identity/items"
        },
        {
          "type": "null"
        }
      ],
      "description": "The wide one, behind the name on its card. Null takes it off."
    },
    "sheet": {
      "anyOf": [
        {
          "$ref": "#/properties/identity/items"
        },
        {
          "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": {
      "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,
      "description": "A voice to bind, so tagging this subject into a voice-over arms the audio seat as well as the face."
    },
    "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."
    }
  },
  "required": [
    "name",
    "kind"
  ],
  "additionalProperties": false
}

Related tools

generate_scene_images
Make the still pictures of the scenes you name.
export_storyboard_video
Copy a finished film into the library as an ordinary clip, and get the file's link.

Every tool· This page as Markdown