Control a Character

Use CometAPI with Runway Control a character API to start character performance tasks from a reference video, driving facial expressions and body motion.

POST /runwayml/v1/character_performance

Create a Runway character-performance task

cURL

curl --request POST \
  --url https://api.cometapi.com/runwayml/v1/character_performance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Runway-Version: <x-runway-version>' \
  --data '
{
  "character": {
    "type": "video",
    "uri": "https://filesystem.site/cdn/20250818/wAKbHUoj5EHyqZvEdJbFXn10wXBMUn.mp4"
  },
  "reference": {
    "type": "video",
    "uri": "https://filesystem.site/cdn/20250818/wAKbHUoj5EHyqZvEdJbFXn10wXBMUn.mp4"
  },
  "bodyControl": true,
  "expressionIntensity": 3,
  "seed": 4294967295,
  "model": "act_two",
  "ratio": "1280:720",
  "contentModeration": {
    "publicFigureThreshold": "auto"
  }
}
'

200

{
  "id": "<string>"
}

Use this endpoint to transfer performance from a reference clip onto a character image or character video.

Before you call it

• Send the required X-Runway-Version header, for example 2024-11-06
• Use model: act_two
• Provide one character asset and one reference asset as accessible HTTPS URLs
• Start with bodyControl: true and a moderate expressionIntensity before tuning style

Task flow

1. Submit the character-performance request

   Create the task with your character asset, reference asset, and motion settings.

2. Store the returned task id

   Keep the returned id, because you need it for later polling.

3. Poll task status

   Continue with Get Task Details until the wrapper reaches a terminal state and provider metadata includes the finished output.

Input roles

• character is the subject you want to animate
• reference is the source clip that provides facial performance or body motion
• bodyControl decides whether motion transfer includes body movement in addition to expression transfer
• contentModeration applies provider moderation thresholds to the request

Authorizations

Authorization · string · header · required

Bearer token authentication. Use your CometAPI key.

Headers

X-Runway-Version · string · required

Runway version header, for example 2024-11-06.

Body

application/json

character · object · required

The character to control. You can either provide a video or an image.

Show child attributes

reference · object · required

Reference performance clip. Provide type (video) and uri (HTTPS URL).

Show child attributes

bodyControl · boolean · default: true · required

Enable body control.

expressionIntensity · integer · default: 1 · required

Intensity of the expression transfer. Higher values produce more exaggerated expressions.

seed · integer · default: 1 · required

Random seed for reproducible results.

model · string · default: act_two · required

The model variant to use. Must be act_two.

ratio · string · default: 1280:720 · required

Aspect ratio of the output video, e.g. 1280:720.

contentModeration · object · required

Show child attributes

Response

200 - application/json

Task accepted.

id · string · required