引用

当你用自己的文件通过 API 创建讲解视频时，可以让旁白引用这些文件。这样每句口述都会记录它讲的是哪个文件的哪一部分，你可以把这些信息作为数据读出来。

你可以用它在视频旁边显示出处，对照原文件核对课程内容，或者把一句旁白链接到它所描述的具体代码行。

开启引用

在创建请求中发送 cite_attachments: true，并至少附上一个文本附件。讲解视频在编写时就带上引用；它的页面不会有任何变化。

bash

curl -s "$SCRIMBA/api/v1/explainers" \
  -H "Authorization: Bearer $SCRIMBA_KEY" \
  -F "prompt=Walk through how this handler checks the token" \
  -F "cite_attachments=true" \
  -F "[email protected]"

只会引用文本和代码文件，绝不会引用图片或 PDF。不带 cite_attachments 时，讲解视频照常生成，每个引用列表都为空。既不是 true 也不是 false 的值会返回 400 invalid_cite_attachments。

读取引用

讲解视频就绪后，GET /api/v1/explainers/:id/transcript 会把旁白作为一组记录返回，每个口述片段一条，按播放顺序排列。每条记录的引用放在 references 里。

json

{
  "index": 3,
  "slide": 2,
  "title": "Checking the token",
  "text": "The handler reads the token from the header, then compares it to the stored secret.",
  "references": [
    {
      "text": "reads the token from the header",
      "text_start": 12,
      "text_end": 43,
      "attachment": 1,
      "offset": 412,
      "length": 39,
      "lines": [10, 10],
      "cited_text": "const token = req.headers.authorization"
    }
  ]
}

一条引用把旁白中的文字和文件中的一段对应起来：

text、text_start 和 text_end 是该记录中被这条引用支撑的文字，以及它们在记录 text 中的位置。
attachment 是文件，用讲解视频对象在 attachments 中列出的 ref 编号表示。
offset、length、lines 和 cited_text 是该文件中被引用的片段：按字符计的位置、从 1 开始计数的首行和末行，以及文字本身。

讲解视频仍在生成中或已失败时，该端点返回 409 not_ready。

可以预期什么

引用什么由模型决定。它会引用某个要点所出自的句子、值或段落，取最小有用的部分；一个片段可以带多条引用，指向一个或多个文件。没有从文件中讲授内容的句子没有引用。

当旁白没有按原文逐字说出所引文字时，text_start 和 text_end 为 null；这种情况下请自行在 text 中匹配。
文本文件最多读取 30,000 个字符，offset 在已读取的范围内计数。
在文件中找不到所引片段的引用会被省略。

逐字段的参考说明见讲解视频 API。

引用 ​

开启引用 ​

读取引用 ​

可以预期什么 ​

引用

开启引用

读取引用

可以预期什么