D-ID 快速上手：API 密钥、实时智能体与视频生成

D-ID 是一套围绕数字人（talking avatar）构建的 API 平台，它把「让一张图片或一段视频开口说话」这件事拆成了可编程的接口。平台提供两条主要接入路径：一条是 Realtime，用 WebRTC 把数字人、大语言模型和自定义知识库组合成可以实时对话的智能体；另一条是 Videos，用异步任务把图片、文本和音频合成为视频。前者适合客服、导览、陪伴类交互场景，后者适合批量生产讲解视频、多语言配音和数字主播内容。如果你需要先确认站内是否已有对应的工具入口，可以查看 D-ID 页面，再回到本文按步骤接入 API。

本文面向需要直接调用 HTTP 接口的开发者，覆盖密钥获取、鉴权方式、实时智能体的搭建流程、记忆与知识库的配置、工具调用，以及各代视频接口的差异。所有请求示例都以命令行形式给出，便于直接复制验证。

准备工作

在写第一行请求之前，需要先确认三件事：账号、密钥和调用方式。

账号与 API 密钥

API 密钥在工作室（studio）的账号设置页面生成。生成后请妥善保存，密钥是私有凭据，不要写进前端代码或公开仓库。平台按调用量计费，具体价格、免费额度与各接口的配额请以官网当前信息为准，本文不给出具体数字。

鉴权方式

D-ID 使用 HTTP Basic Authentication。每一次 API 请求都要在请求头里带上密钥，格式如下：

Header	Value
Authorization	Basic API_USERNAME:API_PASSWORD

也就是说，把用户名和密码用冒号拼接后做 Base64 编码，前面加上 Basic 前缀。在 curl 里可以直接用 -u 参数让工具自动完成编码，也可以手动传入已经编码好的字符串。下面统一用 <YOUR_KEY> 代表这段编码后的凭据。

接口能力总览

在动手之前，先了解平台提供的主要能力，有助于判断该走哪条路径：

Agents：可交互的实时数字人，支持挂载知识库与工具，用于客户互动场景。
V4 Expressive Avatars：全高清视频，支持动态表情与情绪（sentiment）控制。
V3 Pro Avatars：基于高质量视频形象生成全高清视频，形象带有自然的肢体动作。
V3 Instant Avatars：用你自己拍摄的短视频生成专属形象，无需训练过程。
V2 Avatars：基于照片的形象，配合脚本文本生成说话视频。
Video Translate：翻译语音、克隆音色并做口型同步，用于内容本地化。

此外还有一组资源类接口，用于管理音色（Voices）、图片、音频、额度（Credits）、授权同意（Consents）、Logo、密钥（Secrets）、发音词典（Pronunciation Dictionaries）和品牌（Brandings）。这些接口不直接产出内容，但在完整的产品流程里会用到。

操作步骤

第一步：验证密钥是否可用

拿到密钥后，先用一个轻量接口确认鉴权通过。查询额度是一个合适的选择：

curl -X GET "https://api.d-id.com/credits" \
  -H "Authorization: Basic <YOUR_KEY>"

如果返回正常，说明密钥有效，可以继续后面的步骤。如果返回鉴权错误，先检查 Base64 编码是否正确、冒号是否被误删。

第二步：选择接入路径

平台把能力分成实时与异步两大块，两者的调用模型完全不同：

Realtime：智能体通过 WebRTC 串流，延迟低，适合双向对话。你需要先创建 Agent，再创建 Session，然后通过 SDK 建立连接。
Videos：提交任务后轮询或等待回调，产出的是一个视频文件。适合不需要即时响应的场景。

两条路径可以共存，但建议先跑通其中一条再扩展。

第三步：创建智能体（Realtime 路径）

智能体是实时路径的核心对象，它定义了形象、性格和行为。创建接口为 POST /agents：

curl -X POST "https://api.d-id.com/agents" \
  -H "Authorization: Basic <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "preview_name": "My Agent",
    "presenter": { "type": "talk" },
    "llm": { "instructions": "You are a helpful assistant." }
  }'

创建成功后，响应里会返回一个形如 agt_abc123 的智能体 ID，后续所有针对该智能体的操作都要用到它。围绕智能体还有一组管理接口：

GET /agents：列出当前账号下的智能体。
GET /agents/{id}：获取单个智能体的详情。
PATCH /agents/{id}：更新智能体配置，例如开启记忆、调整指令。
DELETE /agents/{id}：删除智能体。

第四步：配置客户端密钥

如果要把智能体嵌入到网页里，不应该把主密钥暴露给浏览器。平台提供了客户端密钥（Client Key）机制，配合可嵌入的 UI 使用，前端无需后端代码即可完成部署。相关接口包括：

POST /agents/{id}/client-keys：为某个智能体创建客户端密钥。
GET /agents/{id}/client-keys：列出该智能体的所有客户端密钥。
PATCH /agents/{id}/client-keys/{key_id}：更新客户端密钥。
DELETE /agents/{id}/client-keys/{key_id}：删除客户端密钥。

客户端密钥是公开可暴露的凭据，主密钥则必须留在服务端。这条边界不要弄反。

第五步：建立会话与串流

会话（Session）代表一次具体的对话。相关接口分布在两个版本下：

POST /agents/sessions：创建新会话。
GET /agents/sessions：列出会话。
GET /agents/sessions/{id}：获取会话详情。
DELETE /agents/sessions/{id}：删除会话。
GET /agents/sessions/{id}/recording-quota：查询该会话的录制额度。

串流相关的接口负责把媒体通道建起来：

POST /agents/streams：创建新的串流。
POST /agents/streams/{id}/webrtc：启动 WebRTC 连接。
POST /agents/streams/{id}/network：提交网络信息，用于 ICE 协商。
POST /agents/streams/{id}/video：创建视频流。
DELETE /agents/streams/{id}：删除视频流。

会话内还可以创建聊天（Chat）并发送消息：POST /agents/chats 创建聊天，POST /agents/chats/{id}/messages 发送消息。对话记录可以通过 Chat Exports 导出：POST /chats/exports 创建导出任务，GET /chats/exports 获取导出结果，格式为结构化 JSON，便于做分析。

第六步：配置知识库

知识库（Knowledge）基于 RAG 机制，让智能体在回答时能引用你上传的文档。相关接口：

POST /knowledge：创建知识库。
GET /knowledge：列出知识库。
GET /knowledge/{id}：获取单个知识库。
PATCH /knowledge/{id}：更新知识库。
DELETE /knowledge/{id}：删除知识库。

文档是知识库的下级资源：POST /knowledge/{id}/documents 上传文档，GET /knowledge/{id}/documents 列出文档，GET /knowledge/{id}/documents/{doc_id} 获取单个文档，DELETE /knowledge/{id}/documents/{doc_id} 删除文档。上传的文档会作为上下文来源参与检索。

第七步：开启记忆

记忆（Memories）让智能体跨会话记住终端用户的事实信息。开启方式是对已有智能体发一个 PATCH 请求：

curl -X PATCH "https://api.d-id.com/agents/<YOUR_AGENT_ID>" \
  -H "Authorization: Basic <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "memory": {
      "enabled": true,
      "scope": "user"
    }
  }'

响应会回显配置：

{
  "id": "agt_abc123",
  "preview_name": "My Agent",
  "memory": {
    "enabled": true,
    "scope": "user"
  }
}

scope 有两个取值："user" 是默认值，表示记忆在所有智能体之间共享；"agent" 表示记忆只隔离在当前智能体内。

开启之后，与智能体进行一次至少 4 条消息的对话。记忆抽取只在会话结束且消息数达到下限时触发，会话结束后抽取器在后台运行，你不需要做任何额外操作。抽取完成后，等待 5 分钟再读取记忆文档。读取时用终端用户的 ID 作为记忆 ID：

curl -X GET "https://api.d-id.com/memories/<END_USER_ID>" \
  -H "Authorization: Basic <YOUR_KEY>"

如果 scope 设成了 "agent"，记忆 ID 要写成 <END_USER_ID>~<AGENT_ID> 的形式。返回结果类似：

{
  "items": [
    {
      "id": "mi_abc123def456",
      "data": "User prefers morning meetings.",
      "priority": 3,
      "created_at": "2024-06-15T09:30:00Z"
    },
    {
      "id": "mi_xyz789ghi012",
      "data": "User is training for a half-marathon in May.",
      "priority": 4,
      "created_at": "2024-06-15T09:30:01Z"
    }
  ]
}

items 里的每一条都是从对话中抽取出来的持久事实，字段包括唯一 ID、事实内容、优先级和创建时间。这些事实会在下一次会话开始时自动注入智能体的上下文，无需手动拼装提示词。

第八步：挂载工具

工具（Tools）让智能体在对话中调用外部能力。工具本身是一组 CRUD 接口：

POST /tools：创建工具。
GET /tools：列出工具。
GET /tools/{ids}：按 ID 批量获取工具。
GET /tools/{id}：获取单个工具。
PUT /tools/{id}：更新工具。
DELETE /tools/{id}：删除工具。

工具分为客户端工具（Client Tools）和服务端工具两类，前者在客户端执行，后者由平台侧调用。工具需要定义 schema 来描述参数结构，并配置授权方式（Authorization Options）。定义完成后，把工具挂载到智能体上即可生效。

第九步：生成视频（Videos 路径）

视频路径是异步的，提交任务后拿到 ID，再查询结果。不同代际的接口路径不同，按需选择：

能力	创建	查询列表	查询单个	删除
V2 Avatars	POST /talks	GET /talks	GET /talks/{id}	DELETE /talks/{id}
V3 Pro Avatars	POST /clips	GET /clips	GET /clips/{id}	DELETE /clips/{id}
V3 Instant Avatars	POST /scenes	GET /scenes	GET /scenes/{id}	DELETE /scenes/{id}
V4 Expressive Avatars	POST /videos	GET /videos	GET /videos/{id}	DELETE /videos/{id}
Video Translate	POST /video-translates	GET /video-translates	GET /video-translates/{id}	DELETE /video-translates/{id}
Agentic Videos	POST /agentic-videos	GET /agentic-videos	GET /agentic-videos/{id}	DELETE /agentic-videos/{id}

V3 Pro 还额外提供形象管理接口：POST /clips/presenters 创建 Premium+ 形象，GET /clips/presenters 列出可用主播，GET /clips/presenters/{id} 按 ID 获取主播，DELETE /clips/presenters/{id} 删除主播。V3 Instant 同样有形象管理：POST /scenes/avatars 创建 Express 形象，GET /scenes/avatars 列出形象，GET /scenes/avatars/{id} 获取形象，DELETE /scenes/avatars/{id} 删除形象。V4 则通过 GET /videos/avatars 列出所有表现力形象，GET /videos/avatars/{id} 按 ID 获取。

Agentic Videos 除了创建、列表、查询、删除之外，还支持 PATCH /agentic-videos/{id} 更新。

第十步：管理资源类对象

资源类接口是内容生产的前置依赖，主要包括：

Voices：GET /voices 获取可用音色，POST /voices 克隆音色，DELETE /voices/{id} 删除音色。平台集成了 ElevenLabs、Microsoft Speech、Amazon Polly 和 Cartesia 等音色来源。
Images：POST /images 上传图片，DELETE /images/{id} 删除图片。
Audios：POST /audios 上传音频文件，DELETE /audios/{id} 删除音频。
Credits：GET /credits 查询额度。
Consents：POST /consents 创建授权同意，GET /consents 列出当前用户的全部同意记录，POST /consents/{id}/video 上传同意视频，GET /consents/{id} 获取单条记录，DELETE /consents/{id} 删除记录。
Settings：GET /settings/logo 获取 Logo，POST /settings/logo 上传 Logo，DELETE /settings/logo 删除 Logo。
Secrets：POST /secrets 创建密钥，GET /secrets 列出密钥，GET /secrets/{id} 获取密钥，PUT /secrets/{id} 更新密钥，DELETE /secrets/{id} 删除密钥。
Pronunciation Dictionaries：POST /pronunciation-dictionaries 创建词典，GET /pronunciation-dictionaries 列出词典，GET /pronunciation-dictionaries/{id} 获取词典，PATCH /pronunciation-dictionaries/{id} 修改词典，DELETE /pronunciation-dictionaries/{id} 删除词典，POST /pronunciation-dictionaries/{id}/clone 克隆词典。
Brandings：POST /brandings 创建品牌，GET /brandings 列出品牌，GET /brandings/{id} 获取品牌，PATCH /brandings/{id} 更新品牌，DELETE /brandings/{id} 删除品牌。

第十一步：接入第三方集成

平台提供若干现成集成，减少自建工作量：

ElevenLabs Agent：POST /integrations/elevenlabs 创建，PATCH /integrations/elevenlabs/{id} 更新。
LiveKit：可以控制智能体、订阅媒体轨道、监听智能体事件。
Vision Client Tools：把视觉能力作为客户端工具接入。
MCP Server：通过 MCP 协议接入外部工具生态。

一个完整示例

下面把记忆功能串成一条最小可跑通的链路，从开启配置到读回事实，覆盖三个请求。

第一步，开启记忆。 假设智能体 ID 是 agt_abc123，把记忆范围设为按用户共享：

curl -X PATCH "https://api.d-id.com/agents/agt_abc123" \
  -H "Authorization: Basic <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "memory": {
      "enabled": true,
      "scope": "user"
    }
  }'

返回体里 memory.enabled 为 true，说明配置已生效。

第二步，进行一次对话。 用该智能体创建会话，与它交换至少 4 条消息。消息数不足时不会触发抽取，所以这一步不能省。会话结束后抽取器自动在后台运行。

第三步，等待并读取记忆。 等待 5 分钟，然后用终端用户 ID 查询：

curl -X GET "https://api.d-id.com/memories/user_12345" \
  -H "Authorization: Basic <YOUR_KEY>"

返回的 items 数组里就是抽取出的持久事实，每条带有 id、data、priority 和 created_at。这些事实会在下一次会话开始时自动进入智能体上下文，因此第二次对话时智能体就能自然地引用第一次对话里出现过的信息。

如果希望记忆只在单个智能体内生效，把 scope 改成 "agent"，读取时把记忆 ID 写成 user_12345~agt_abc123 即可。

注意事项

以下几点在接入过程中容易踩坑，值得提前留意。

记忆抽取有触发条件。 抽取只在会话结束且消息数达到下限（至少 4 条）时触发。消息太少不会有任何记忆产出，这不是接口故障。

读取记忆需要等待。 会话结束后抽取器在后台运行，官方给出的等待时间是 5 分钟。过早查询可能拿到空结果。

记忆 ID 的构造方式取决于 scope。 scope 为 "user" 时直接用终端用户 ID；为 "agent" 时必须写成 <END_USER_ID>~<AGENT_ID>。写错格式会查不到数据。

主密钥与客户端密钥的边界。 主密钥只能留在服务端；嵌入网页时使用客户端密钥配合可嵌入 UI，前端不需要后端代码。把主密钥放进浏览器会直接暴露账号权限。

视频接口是异步的。 提交后拿到的是任务 ID，需要轮询查询或等待结果，不要期望同步返回视频文件。不同代际的接口路径不同，V2 用 /talks，V3 Pro 用 /clips，V3 Instant 用 /scenes，V4 用 /videos，混用会报错。

音色来源是多家混合的。 平台集成了 ElevenLabs、Microsoft Speech、Amazon Polly 和 Cartesia，不同来源的音色在可用性和表现上可能有差异，选型时以实际查询结果为准。

授权同意是独立流程。 涉及真人形象或音色克隆时，Consents 接口负责记录授权，包含创建记录和上传同意视频两个动作，不要跳过。

价格、额度与配额以官网为准。 本文不给出具体数字，因为计费规则和免费额度会调整。上线前请查询 GET /credits 确认余额，并核对官网当前的定价与限制说明。

把上面这些步骤走一遍，基本就能覆盖从密钥到实时对话、从知识库到视频生成的完整链路。后续扩展时，优先复用已有的智能体配置和工具定义，避免重复创建资源。