Back to Details

runway-dev-characters

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Runway Dev — Characters

Runway Dev — Characters

Companion: Use 
+runway-dev
for shared guidance when available. If it is not installed, inspect the workspace, probe 
RUNWAYML_API_SECRET
without printing it, and read the Characters docs linked by 
llms.txt
. Encourage connecting Dev MCP to inspect or manage characters and knowledge documents. If the user declines or cannot connect, continue integration from current docs and an existing character ID.
配套工具： 若可用，使用
+runway-dev
获取共享指导。如果未安装该工具，请检查工作区，探查
RUNWAYML_API_SECRET
但不要打印它，并阅读
llms.txt
中链接的Characters文档。建议连接Dev MCP以检查或管理角色和知识文档。如果用户拒绝或无法连接，请根据现有文档和已有的角色ID继续集成。

Goal

目标

Keep a Characters integration and its live Session lifecycle correct across the application's backend and UI. Verify changes end-to-end when safe.
确保Characters集成及其实时Session生命周期在应用程序的后端和UI中保持正确。在安全的情况下进行端到端验证。

Terminology

术语

  • Dev Portal Characters = API avatars (
    list_avatars
    , 
    get_avatar
    ).
  • Character ID = avatar UUID.
  • live Session = realtime conversation via 
    POST /v1/realtime_sessions
    .
  • Fallback preset when the user wants a default: 
    influencer
    (
    { type: 'runway-preset', presetId: 'influencer' }
    ).
  • 开发者门户Characters = API中的avatars（
    list_avatars
    、
    get_avatar
    ）。
  • Character ID = avatar UUID。
  • live Session = 通过
    POST /v1/realtime_sessions
    实现的实时对话。
  • 当用户需要默认角色时的 fallback 预设：
    influencer
    （
    { type: 'runway-preset', presetId: 'influencer' }
    ）。

No character specified

未指定角色

  1. Ask whether the user wants an existing character, a preset, or a custom character from an image. Do not branch into avatar-video generation unless requested.
  2. For a custom character, ask the user to supply the image and use 
    create_avatar
    according to its live MCP tool schema. If the user wants a default instead, use preset 
    influencer
    .
  3. Implement the Session lifecycle behind the server boundary: create once, poll 
    NOT_READY
    until 
    READY
    , consume connection credentials once, and return only the connection fields the client needs.
  4. Connect the application's call UI with the current Avatar SDK, then end or cancel the Session during teardown so it does not keep running.
  5. For end-to-end verification, connect one Session successfully and cleanly end it.
  1. 询问用户是需要现有角色、预设角色还是基于图像的自定义角色。除非用户要求，否则不要涉及avatar视频生成。
  2. 对于自定义角色，请用户提供图像，并根据MCP工具的实时schema使用
    create_avatar
    。如果用户想要默认角色，则使用
    influencer
    预设。
  3. 在服务器边界后实现Session生命周期：创建一次，轮询直到状态从
    NOT_READY
    变为
    READY
    ，仅消费一次连接凭证，并仅返回客户端所需的连接字段。
  4. 将应用程序的通话UI与当前Avatar SDK连接，然后在销毁阶段结束或取消Session，避免其持续运行。
  5. 为了进行端到端验证，成功连接一个Session并干净地结束它。

Character specified

指定了角色

  1. get_avatar
    for status and attached knowledge document ids.
  2. Use that character id; do not substitute another avatar.
  3. If status is 
    PROCESSING
    , poll until 
    READY
    or stop on 
    FAILED
    .
  1. 调用
    get_avatar
    获取状态和关联的知识文档ID。
  2. 使用该角色ID；不要替换为其他avatar。
  3. 如果状态为
    PROCESSING
    ，则轮询直到变为
    READY
    或在状态变为
    FAILED
    时停止。

MCP tools

MCP工具

  • list_avatars
    / 
    get_avatar
    — inspect custom avatars in project.
  • create_avatar
    / 
    update_avatar
    / 
    delete_avatar
    — manage custom characters; confirm destructive changes before applying them.
  • list_avatar_knowledge_documents
    / 
    get_avatar_knowledge_document
    — inspect attached knowledge.
  • create_avatar_knowledge_document
    / 
    update_avatar_knowledge_document
    / 
    delete_avatar_knowledge_document
    — manage domain knowledge when requested; confirm deletion first.
  • list_avatars
    / 
    get_avatar
    — 检查项目中的自定义avatars。
  • create_avatar
    / 
    update_avatar
    / 
    delete_avatar
    — 管理自定义角色；在应用破坏性更改前确认。
  • list_avatar_knowledge_documents
    / 
    get_avatar_knowledge_document
    — 检查关联的知识文档。
  • create_avatar_knowledge_document
    / 
    update_avatar_knowledge_document
    / 
    delete_avatar_knowledge_document
    — 根据需求管理领域知识；删除前需确认。

Application UI

应用程序UI

  • Follow the current Avatar SDK README rather than copying component APIs from memory.
  • In React, use 
    @runwayml/avatars-react
    with its stylesheet. Keep session creation and credential consumption on the server; browser code receives only one-time connection fields.
  • Use the packaged call component for standard UI or the SDK hooks for a custom experience. Handle microphone permission, connecting, active, error, and ended states.
  • A failed connection needs a new Session because consumed credentials cannot be reused.
  • 遵循当前Avatar SDK的README，不要凭记忆复制组件API。
  • 在React中，使用
    @runwayml/avatars-react
    及其样式表。将Session创建和凭证消费放在服务器端；浏览器代码仅接收一次性连接字段。
  • 使用打包的通话组件实现标准UI，或使用SDK钩子实现自定义体验。处理麦克风权限、连接中、活跃、错误和结束状态。
  • 连接失败需要创建新的Session，因为已消费的凭证无法重复使用。

Knowledge

知识文档

Use the MCP knowledge-document tools above for live state and CRUD. Inspect attached documents before updating them, keep content focused and structured, and do not delete knowledge without confirmation.
使用上述MCP知识文档工具处理实时状态和CRUD操作。在更新关联文档前先检查内容，保持内容聚焦且结构化，未经确认不要删除知识文档。

Docs

文档