Clipwright

Create a personal actor

create_actor

Generate a personal actor from a text description for UGC videos, including a 9:16 portrait with one face and other formats; poll the run for the actor_id.

Instructions

Input: the same fields as quote_actor, plus attempt. Create a personal actor for this account from words describing a fictional adult: a 9:16 portrait with exactly one face, plus the other requested formats edited from it. Returns a run_id immediately; poll get_run until 'succeeded' (created_actor.actor_id, then pass it as actor_id to make_ugc) or 'failed'. Each published image is charged at the price quote shows; refused descriptions and unusable portraits cost nothing. When generation is switched off the call fails with actor_generation_disabled. With from_actor_id it derives a new personal actor from a library or own actor: the same face (checked; a mismatch costs nothing), with framing wide, objects in holding or a new setting. A held object's picture is an image asset (upload, URL import or a found picture, rights_confirmed). Price: medium portrait: 4 credits per image; medium other format: 8 credits per image; high portrait: 12 credits per image; high other format: 18 credits per image. Quote first with quote_actor; list_prices names every price.

Input Schema

Name	Required	Description	Default
`name`	Yes
`gender`	No
`attempt`	No
`framing`	No
`holding`	No
`quality`	No
`setting`	No
`description`	No
`aspect_ratios`	No
`from_actor_id`	No
`approximate_age`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed35 schema fields changedv0.39.0Nov 3, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

removedInput schema / properties / approximate_age / description

Removed value: -"Approximate age in years, 18 to 90: actors are adults. Required unless from_actor_id is given."

removedInput schema / properties / approximate_age / maximum
```
Removed value: -90
```
removedInput schema / properties / approximate_age / minimum
```
Removed value: -18
```
removedInput schema / properties / aspect_ratios / default
```
Removed value: -[
-  "9:16",
-  "1:1",
-  "16:9"
-]
```

removedInput schema / properties / aspect_ratios / description

Removed value: -"Formats to create: 9:16 | 1:1 | 16:9, always including 9:16. Omitted means all three. Formats that fail the identity check are not charged and are named in warnings."

removedInput schema / properties / aspect_ratios / items / enum
```
Removed value: -[
-  "9:16",
-  "1:1",
-  "16:9"
-]
```
removedInput schema / properties / aspect_ratios / maxItems
```
Removed value: -3
```
removedInput schema / properties / aspect_ratios / minItems
```
Removed value: -1
```
removedInput schema / properties / attempt / maximum
```
Removed value: -9007199254740991
```
removedInput schema / properties / attempt / minimum
```
Removed value: -1
```

removedInput schema / properties / description / description

Removed value: -"Words describing a fictional adult: appearance, clothing, setting. Naming a real person or a likeness to one is refused before any charge (actor_prompt_refused). Required unless from_actor_id is given."

removedInput schema / properties / description / maxLength
```
Removed value: -500
```
removedInput schema / properties / description / minLength
```
Removed value: -1
```

removedInput schema / properties / framing / description

Removed value: -"wide: the camera further back, the head lower with room above; make_ugc then renders it as a wide view."

removedInput schema / properties / framing / enum
```
Removed value: -[
-  "wide"
-]
```

removedInput schema / properties / from_actor_id / description

Removed value: -"Derive a new personal actor from this one (a library actor or your own): the same face, gender and age, with the view changed by framing, holding or setting. Omit description, gender and approximate_age."

removedInput schema / properties / from_actor_id / pattern
```
Removed value: -"^actor_[a-z0-9][a-z0-9_-]{0,63}$"
```

removedInput schema / properties / gender / description

Removed value: -"female | male. Fixes the actor's gender and the default voice of videos with this actor. Required unless from_actor_id is given."

removedInput schema / properties / gender / enum
```
Removed value: -[
-  "female",
-  "male"
-]
```

removedInput schema / properties / holding / description

Removed value: -"Up to 2 objects the presenter holds, one per hand."

removedInput schema / properties / holding / items / additionalProperties
```
Removed value: -false
```

removedInput schema / properties / holding / items / properties

Removed value: -{
-  "description": {
-    "description": "The object, e.g. \"a white coffee mug\".",
-    "maxLength": 200,
-    "minLength": 1,
-    "type": "string"
-  },
-  "hand": {
-    "description": "left | right; omitted lets the edit choose.",
-    "enum": [
-      "left",
-      "right"
-    ],
-    "type": "string"
-  },
-  "reference": {
-    "additionalProperties": false,
-    "description": "A PNG or JPEG picture of the object: an image asset of this account (upload, URL import or a found picture, rights_confirmed).",
-    "properties": {
-      "asset_id": {
-        "pattern": "^ast_[a-f0-9]{32}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "asset_id"
-    ],
-    "type": "object"
-  }
-}

removedInput schema / properties / holding / items / required
```
Removed value: -[
-  "description"
-]
```
removedInput schema / properties / holding / maxItems
```
Removed value: -2
```
removedInput schema / properties / holding / minItems
```
Removed value: -1
```
removedInput schema / properties / name / description
```
Removed value: -"Name shown in list_actors."
```
removedInput schema / properties / name / maxLength
```
Removed value: -100
```
removedInput schema / properties / name / minLength
```
Removed value: -1
```
removedInput schema / properties / quality / default
```
Removed value: -"medium"
```

removedInput schema / properties / quality / description

Removed value: -"Image quality: medium | high. Omitted means medium. The price per image depends on it; quote shows it before any charge."

removedInput schema / properties / quality / enum
```
Removed value: -[
-  "medium",
-  "high"
-]
```

removedInput schema / properties / setting / description

Removed value: -"The room or background to put the presenter in, in words."

removedInput schema / properties / setting / maxLength
```
Removed value: -300
```
removedInput schema / properties / setting / minLength
```
Removed value: -1
```

Changed8 schema fields changedv0.35.0Oct 30, 2026

changedInput schema / properties / approximate_age / description

Previous value: -"Approximate age in years, 18 to 90: actors are adults."New value: +"Approximate age in years, 18 to 90: actors are adults. Required unless from_actor_id is given."

changedInput schema / properties / description / description

Previous value: -"Words describing a fictional adult: appearance, clothing, setting. Naming a real person or a likeness to one is refused before any charge (actor_prompt_refused)."New value: +"Words describing a fictional adult: appearance, clothing, setting. Naming a real person or a likeness to one is refused before any charge (actor_prompt_refused). Required unless from_actor_id is given."

addedInput schema / properties / framing

Added value: +{
+  "description": "wide: the camera further back, the head lower with room above; make_ugc then renders it as a wide view.",
+  "enum": [
+    "wide"
+  ],
+  "type": "string"
+}

addedInput schema / properties / from_actor_id

Added value: +{
+  "description": "Derive a new personal actor from this one (a library actor or your own): the same face, gender and age, with the view changed by framing, holding or setting. Omit description, gender and approximate_age.",
+  "pattern": "^actor_[a-z0-9][a-z0-9_-]{0,63}$",
+  "type": "string"
+}

changedInput schema / properties / gender / description

Previous value: -"female | male. Fixes the actor's gender and the default voice of videos with this actor."New value: +"female | male. Fixes the actor's gender and the default voice of videos with this actor. Required unless from_actor_id is given."

addedInput schema / properties / holding

Added value: +{
+  "description": "Up to 2 objects the presenter holds, one per hand.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "description": {
+        "description": "The object, e.g. \"a white coffee mug\".",
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "hand": {
+        "description": "left | right; omitted lets the edit choose.",
+        "enum": [
+          "left",
+          "right"
+        ],
+        "type": "string"
+      },
+      "reference": {
+        "additionalProperties": false,
+        "description": "A PNG or JPEG picture of the object: an image asset of this account (upload, URL import or a found picture, rights_confirmed).",
+        "properties": {
+          "asset_id": {
+            "pattern": "^ast_[a-f0-9]{32}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "asset_id"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "description"
+    ],
+    "type": "object"
+  },
+  "maxItems": 2,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / setting

Added value: +{
+  "description": "The room or background to put the presenter in, in words.",
+  "maxLength": 300,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "description",
-  "gender",
-  "approximate_age",
-  "name"
-]New value: +[
+  "name"
+]

First observedv0.20.0Sep 25, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries most of the load and does so well: async run_id with polling contract, credit charging per published image, free refusals and unusable portraits, the actor_generation_disabled error, and face-match verification for from_actor_id. The main gap is that it never states what happens to an existing actor with the same name or whether a failed run leaves partial state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is valuable but the writing is a dense wall of run-on sentences mixing usage, errors, derivation semantics, and a full price table. Front-loading is decent (the create-and-return-run_id contract comes first), yet the enumerated per-format pricing largely duplicates what list_prices and quote_actor provide and hurts scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly explains the return contract (run_id, then created_actor.actor_id on the get_run result) and covers cost, failure, and derivation behavior. Missing pieces are the semantics of the plain descriptive fields (name, gender, approximate_age) and whether billing occurs only on success, which an agent creating an actor would benefit from knowing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% across 11 parameters, so the description must compensate and does so only partially: it clarifies from_actor_id, holding (image asset with rights_confirmed), framing ('wide'), quality tiers via the price table, and the 9:16 default for aspect_ratios. Name, gender, description, approximate_age, attempt, and setting values remain unexplained, leaving several parameters ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a personal actor for this account') and immediately scopes it with concrete constraints: a 9:16 portrait with exactly one face plus derived formats. It also distinguishes itself from siblings by naming quote_actor (for pricing) and make_ugc (consumer of the resulting actor_id), and explains the from_actor_id variant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit workflow routing: quote first with quote_actor, poll get_run until succeeded, then pass created_actor.actor_id to make_ugc. It also names the failure mode when generation is disabled. It stops short of saying when to prefer this over make_faceless or how it relates to list_actors/get_actor_defaults, so it is clear but not fully exclusionary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Create a personal actor

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools