控制角色

使用 CometAPI 搭配 Runway 的控制角色 API，從參考影片啟動角色表演任務，驅動臉部表情與身體動作。

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>"
}

使用此端點可將參考片段中的表演轉移到角色圖片或角色影片上。

​

呼叫前準備

• 傳送必要的 X-Runway-Version 標頭，例如 2024-11-06
• 使用 model: act_two
• 提供一個 character 資產與一個 reference 資產，且都必須是可存取的 HTTPS URL
• 在調整風格前，先以 bodyControl: true 和適中的 expressionIntensity 開始

​

任務流程

1. 提交角色表演請求

   使用你的角色資產、參考資產與動作設定建立任務。

2. 儲存回傳的 task id

   保留回傳的 id，因為後續輪詢時會需要用到。

3. 輪詢任務狀態

   持續使用 取得任務詳細資料，直到封裝器進入終止狀態，且提供者中繼資料包含已完成的輸出。

​

輸入角色

• character 是你想要製作動畫的主體
• reference 是提供臉部表演或身體動作的來源片段
• bodyControl 決定動作轉移是否除了表情轉移外，也包含身體動作
• contentModeration 會將提供者的內容審核門檻套用到該請求

授權

Authorization · string · header · 必填

Bearer token authentication. Use your CometAPI key.

標頭

X-Runway-Version · string · 必填

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

主體

application/json

character · object · 必填

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

Show child attributes

reference · object · 必填

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

Show child attributes

bodyControl · boolean · 預設值: true · 必填

Enable body control.

expressionIntensity · integer · 預設值: 1 · 必填

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

seed · integer · 預設值: 1 · 必填

Random seed for reproducible results.

model · string · 預設值: act_two · 必填

The model variant to use. Must be act_two.

ratio · string · 預設值: 1280:720 · 必填

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

contentModeration · object · 必填

Show child attributes

回應

200 - application/json

Task accepted.

id · string · 必填