官方格式
创建 Runway 角色表演
使用 CometAPI 搭配 Runway Control a character API,从参考视频启动角色表演任务,驱动面部表情和身体动作。
POST
/
runwayml
/
v1
/
character_performance
cURL
curl https://api.cometapi.com/runwayml/v1/character_performance \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"character": {
"type": "video",
"uri": "https://your-video-host/character.mp4"
},
"reference": {
"type": "video",
"uri": "https://your-video-host/performance.mp4"
},
"model": "act_two",
"ratio": "1280:720"
}'import os
import requests
response = requests.post(
"https://api.cometapi.com/runwayml/v1/character_performance",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"character": {
"type": "video",
"uri": "https://your-video-host/character.mp4"
},
"reference": {
"type": "video",
"uri": "https://your-video-host/performance.mp4"
},
"model": "act_two",
"ratio": "1280:720"
},
)
task = response.json()
print(task["id"]) # poll GET /runwayml/v1/tasks/{id} until the output array appearsconst response = await fetch("https://api.cometapi.com/runwayml/v1/character_performance", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"character": {
"type": "video",
"uri": "https://your-video-host/character.mp4"
},
"reference": {
"type": "video",
"uri": "https://your-video-host/performance.mp4"
},
"model": "act_two",
"ratio": "1280:720"
}),
});
const task = await response.json();
console.log(task.id); // poll GET /runwayml/v1/tasks/{id} until the output array appears<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cometapi.com/runwayml/v1/character_performance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'character' => [
'type' => 'video',
'uri' => 'https://your-video-host/source.mp4'
],
'reference' => [
'type' => 'video',
'uri' => 'https://your-video-host/source.mp4'
],
'bodyControl' => true,
'expressionIntensity' => 3,
'seed' => 4294967295,
'model' => 'act_two',
'ratio' => '1280:720',
'contentModeration' => [
'publicFigureThreshold' => 'auto'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Runway-Version: <x-runway-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cometapi.com/runwayml/v1/character_performance"
payload := strings.NewReader("{\n \"character\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"reference\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"bodyControl\": true,\n \"expressionIntensity\": 3,\n \"seed\": 4294967295,\n \"model\": \"act_two\",\n \"ratio\": \"1280:720\",\n \"contentModeration\": {\n \"publicFigureThreshold\": \"auto\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Runway-Version", "<x-runway-version>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cometapi.com/runwayml/v1/character_performance")
.header("X-Runway-Version", "<x-runway-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"character\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"reference\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"bodyControl\": true,\n \"expressionIntensity\": 3,\n \"seed\": 4294967295,\n \"model\": \"act_two\",\n \"ratio\": \"1280:720\",\n \"contentModeration\": {\n \"publicFigureThreshold\": \"auto\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cometapi.com/runwayml/v1/character_performance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Runway-Version"] = '<x-runway-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"character\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"reference\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"bodyControl\": true,\n \"expressionIntensity\": 3,\n \"seed\": 4294967295,\n \"model\": \"act_two\",\n \"ratio\": \"1280:720\",\n \"contentModeration\": {\n \"publicFigureThreshold\": \"auto\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "5b91e444-c232-deaf-a4d7-8aef3e57336b"
}使用此端点可将参考片段中的表演迁移到角色图片或角色视频上。
调用前准备
- 发送必需的
X-Runway-Version请求头,例如2024-11-06 - 使用
model: act_two - 提供一个
character资源和一个reference资源,且它们都必须是可访问的 HTTPS URL - 在调整风格前,先以
bodyControl: true和适中的expressionIntensity开始
输出比例
| 设置 | 支持的值 | 默认起始值 | 边界行为 |
|---|---|---|---|
ratio | 1280:720、720:1280,或所选 Runway model/版本接受的其他比例 | 1280:720 | 让角色和参考资源尽量接近所请求的画面比例。 |
任务流程
1
提交角色表演请求
使用你的角色资源、参考资源和动作设置创建任务。
2
保存返回的任务 id
保留返回的
id,因为后续轮询时需要用到它。3
轮询任务状态
继续使用 获取 Runway 任务,直到任务进入终态,且 provider 元数据包含已完成的输出。
输入角色
character是你想要添加动画效果的主体reference是提供面部表演或身体动作的源片段bodyControl决定动作迁移是否除表情迁移外还包含身体运动contentModeration将 provider 的内容审核阈值应用到该请求
授权
Bearer token authentication. Use your CometAPI key.
请求头
Runway version header, for example 2024-11-06.
请求体
application/json
The character to control. You can either provide a video or an image.
Show child attributes
Show child attributes
Reference performance clip. Provide type (video) and uri (HTTPS URL).
Show child attributes
Show child attributes
Enable body control.
Intensity of the expression transfer. Higher values produce more exaggerated expressions.
Random seed for reproducible results.
The model variant to use. Must be act_two.
Requested output frame shape, for example 1280:720 or 720:1280. Keep the character and reference assets close to the requested frame shape.
Show child attributes
Show child attributes
响应
200 - application/json
Task accepted.
⌘I
cURL
curl https://api.cometapi.com/runwayml/v1/character_performance \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"character": {
"type": "video",
"uri": "https://your-video-host/character.mp4"
},
"reference": {
"type": "video",
"uri": "https://your-video-host/performance.mp4"
},
"model": "act_two",
"ratio": "1280:720"
}'import os
import requests
response = requests.post(
"https://api.cometapi.com/runwayml/v1/character_performance",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"character": {
"type": "video",
"uri": "https://your-video-host/character.mp4"
},
"reference": {
"type": "video",
"uri": "https://your-video-host/performance.mp4"
},
"model": "act_two",
"ratio": "1280:720"
},
)
task = response.json()
print(task["id"]) # poll GET /runwayml/v1/tasks/{id} until the output array appearsconst response = await fetch("https://api.cometapi.com/runwayml/v1/character_performance", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"character": {
"type": "video",
"uri": "https://your-video-host/character.mp4"
},
"reference": {
"type": "video",
"uri": "https://your-video-host/performance.mp4"
},
"model": "act_two",
"ratio": "1280:720"
}),
});
const task = await response.json();
console.log(task.id); // poll GET /runwayml/v1/tasks/{id} until the output array appears<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cometapi.com/runwayml/v1/character_performance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'character' => [
'type' => 'video',
'uri' => 'https://your-video-host/source.mp4'
],
'reference' => [
'type' => 'video',
'uri' => 'https://your-video-host/source.mp4'
],
'bodyControl' => true,
'expressionIntensity' => 3,
'seed' => 4294967295,
'model' => 'act_two',
'ratio' => '1280:720',
'contentModeration' => [
'publicFigureThreshold' => 'auto'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Runway-Version: <x-runway-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cometapi.com/runwayml/v1/character_performance"
payload := strings.NewReader("{\n \"character\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"reference\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"bodyControl\": true,\n \"expressionIntensity\": 3,\n \"seed\": 4294967295,\n \"model\": \"act_two\",\n \"ratio\": \"1280:720\",\n \"contentModeration\": {\n \"publicFigureThreshold\": \"auto\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Runway-Version", "<x-runway-version>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cometapi.com/runwayml/v1/character_performance")
.header("X-Runway-Version", "<x-runway-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"character\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"reference\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"bodyControl\": true,\n \"expressionIntensity\": 3,\n \"seed\": 4294967295,\n \"model\": \"act_two\",\n \"ratio\": \"1280:720\",\n \"contentModeration\": {\n \"publicFigureThreshold\": \"auto\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cometapi.com/runwayml/v1/character_performance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Runway-Version"] = '<x-runway-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"character\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"reference\": {\n \"type\": \"video\",\n \"uri\": \"https://your-video-host/source.mp4\"\n },\n \"bodyControl\": true,\n \"expressionIntensity\": 3,\n \"seed\": 4294967295,\n \"model\": \"act_two\",\n \"ratio\": \"1280:720\",\n \"contentModeration\": {\n \"publicFigureThreshold\": \"auto\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "5b91e444-c232-deaf-a4d7-8aef3e57336b"
}