create-structured-output

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vapi Structured Output Creation

Vapi 结构化输出创建

Build the smallest reusable post-call extraction that represents the user's actual downstream contract. Keep definition creation, assistant attachment, execution, and result retrieval separate: success at one stage does not prove the next stage occurred.

构建最小的可复用通话后提取逻辑，以匹配用户实际的下游契约。将定义创建、助手关联、执行和结果检索步骤分开：某一步骤成功不代表后续步骤已完成。

Source and Safety Rules

来源与安全规则

Use the configured Vapi documentation MCP when available. Otherwise use current public Vapi API documentation and API Examples. Revalidate request fields and SDK methods before final implementation.
Use a private Vapi API key only on a trusted server. Read it from
```
VAPI_API_KEY
```
; never print, request in chat, or embed it in source, client-side code, or examples.
Never invent resource IDs, call IDs, extraction fields, enum values, data-retention requirements, or customer data.
Do not enable
```
compliancePlan.forceStoreOnHipaaEnabled
```
unless the user explicitly requests it and confirms that the output cannot contain PHI or other sensitive data.
Treat call transcripts, messages, tool results, and extracted values as sensitive customer data. Minimize what is logged or reproduced.

优先使用已配置的Vapi文档MCP；若无，则使用当前公开的Vapi API文档和API示例。在最终实现前重新验证请求字段和SDK方法。
仅在可信服务器上使用私有Vapi API密钥。从
```
VAPI_API_KEY
```
读取密钥；切勿打印、在聊天中索要，或嵌入到源代码、客户端代码或示例中。
不得虚构资源ID、通话ID、提取字段、枚举值、数据保留要求或客户数据。
除非用户明确要求并确认输出不会包含PHI或其他敏感数据，否则不要启用
```
compliancePlan.forceStoreOnHipaaEnabled
```
。
将通话记录、消息、工具结果和提取值视为敏感客户数据，尽量减少日志记录或复制的内容。

Procedure

操作流程

Choose the output mode.
- For a schema, payload, review, or implementation example, return an artifact without calling Vapi. State that nothing was saved, attached, or executed.
- For a reusable saved definition, use
```
POST /structured-output
```
  only when the user asks to create or save it and credentials are available.
- For a one-call experiment that does not need a saved definition, pass a transient
```
structuredOutput
```
  to
```
POST /structured-output/run
```
  with
```
previewEnabled: true
```
  .
- Treat attachment, detachment, and execution against existing calls as separate requested actions. Do not infer them from creation alone.
Define the extraction contract.
- Identify the downstream consumer, required fields, optional fields, allowed categories, formats, and behavior when evidence is absent or ambiguous.
- Ask only for missing facts that materially change the schema. State safe assumptions for the rest.
- Split unrelated outputs when they have different consumers, retention policies, or iteration cycles. Keep one output when the fields form one stable business record.
Choose AI or regex.
- Use
```
type: "ai"
```
  for meaning, classification, summarization, sentiment, outcome detection, normalization, or facts expressed in varied language.
- Use
```
type: "regex"
```
  only for deterministic transcript matching with a stable pattern. Use RE2-compatible syntax and choose a top-level schema type that matches the documented regex result: boolean, string, number/integer, or array.
- Do not use regex to infer meaning. Do not use AI when a literal, stable pattern is the entire requirement.
Design the smallest useful JSON Schema.
- Include only fields the caller can provide or the call evidence can support.
- Add concise descriptions that distinguish semantically similar fields.
- Use
```
enum
```
  for a closed category set,
```
format
```
  or
```
pattern
```
  for externally validated strings, and numeric bounds when the business contract defines them.
- Mark a field required only when every valid call should produce it. Make conditionally available values optional instead of forcing guesses.
- Prefer a primitive schema for a single value and an object only for a cohesive record. Avoid deep nesting unless the downstream contract needs it.
- Validate the schema with a standard JSON Schema validator before sending it.
Create, inspect, or update the definition.
- Keep saved names between 1 and 40 characters.
- On create, send
```
name
```
  and
```
schema
```
  ; add
```
type
```
  ,
```
description
```
  ,
```
regex
```
  ,
```
model
```
  , or
```
compliancePlan
```
  only when intentional.
- On inspect, resolve the exact resource with list filters or a verified ID, then use
```
GET /structured-output/{id}
```
  . Do not guess from a partial name.
- On update, read the current definition first and send only fields that should change. Use
```
schemaOverride=true
```
  only when intentionally changing the schema's top-level type; otherwise do not use it to bypass schema safety.
- Re-fetch after mutation and compare the requested fields. A successful HTTP status without the expected returned state is not verified success.
Attach or detach safely.
- Prefer the saved Structured Output's documented
```
assistantIds
```
  relationship for attachment. Read its current
```
assistantIds
```
  , add or remove exactly the resolved assistant ID, and preserve every unrelated ID.
- Patch only
```
assistantIds
```
  on the Structured Output for this operation. Re-fetch the Structured Output and assistant; verify the relationship and the assistant's
```
artifactPlan.structuredOutputIds
```
  when returned.
- If the implementation instead patches the assistant, first read the assistant and send the complete existing
```
artifactPlan
```
  with only
```
structuredOutputIds
```
  changed. Preserve recording, logging, transcript, scorecard, storage, and other artifact settings.
- Do not claim that creating a definition attached it. Do not claim that detaching deleted it or removed results already stored on past calls.
Preview before broad execution.
- Use
```
POST /structured-output/run
```
  with one real call ID and
```
previewEnabled: true
```
  . Supply either
```
structuredOutputId
```
  or a transient
```
structuredOutput
```
  , not both.
- Confirm the selected call contains representative evidence and that the returned value satisfies the schema and business meaning.
- State that preview does not update the call artifact.
- If extraction is wrong, simplify the schema or improve descriptions before changing models or custom extraction prompts.
Execute or backfill only when requested.
- Use
```
previewEnabled: false
```
  or omit it to update call artifacts. Pass no more than the currently documented maximum of 100 call IDs per request.
- Before a multi-call run, state the exact output, call count, and that existing values for this output may be replaced while other structured-output values remain.
- Use only call IDs supplied by the user or returned by a verified public API query. Report partial failures by call ID; do not imply an all-or-nothing transaction.
Retrieve and verify results.
- After a normal attached call finishes, allow for post-call processing before checking the call.
- Retrieve each call with
```
GET /call/{id}
```
  and read
```
call.artifact.structuredOutputs[structuredOutputId].result
```
  .
- Validate the result against the intended schema and inspect representative source evidence before calling it accurate. Schema validity proves shape, not factual correctness.
- Report separately: definition saved, assistant linked, preview returned, call artifact updated, and result validated. Mention only stages actually verified.

选择输出模式。
- 若仅需生成 schema、负载、评审或实现示例，直接返回工件即可，无需调用Vapi。说明未保存、关联或执行任何操作。
- 若需创建可复用的已保存定义，仅当用户要求创建或保存且凭据可用时，才使用
```
POST /structured-output
```
  接口。
- 若需进行无需保存定义的单次通话实验，可将临时
```
structuredOutput
```
  传入
```
POST /structured-output/run
```
  接口，并设置
```
previewEnabled: true
```
  。
- 将关联、取消关联以及针对现有通话执行的操作视为独立的请求动作，不得仅从创建操作推断这些动作。
定义提取契约。
- 明确下游消费者、必填字段、可选字段、允许的类别、格式，以及证据缺失或模糊时的处理逻辑。
- 仅询问会实质性改变schema的缺失信息，其余部分说明安全假设。
- 当下游消费者、保留策略或迭代周期不同时，拆分不相关的输出；当字段构成一个稳定的业务记录时，保留单一输出。
选择AI或正则表达式方式。
- 当需要处理语义、分类、摘要、情感、结果检测、归一化，或语言表达多样的事实时，使用
```
type: "ai"
```
  。
- 仅当需要对稳定模式进行确定性通话记录匹配时，使用
```
type: "regex"
```
  。采用RE2兼容语法，并选择与文档中正则表达式结果匹配的顶级schema类型：布尔值、字符串、数字/整数或数组。
- 不得使用正则表达式推断语义；当需求仅为匹配字面稳定模式时，不得使用AI。
设计最小可用的JSON Schema。
- 仅包含调用者可提供或通话证据可支持的字段。
- 添加简洁描述以区分语义相似的字段。
- 对封闭类别集使用
```
enum
```
  ，对需外部验证的字符串使用
```
format
```
  或
```
pattern
```
  ，当业务契约有定义时使用数值边界。
- 仅当每个有效通话都应生成该字段时，才标记为必填。对于条件可用的值，设为可选而非强制猜测。
- 单个值优先使用基本类型schema，仅当需要连贯记录时使用对象类型。除非下游契约要求，否则避免深度嵌套。
- 在发送前使用标准JSON Schema验证器验证schema。
创建、检查或更新定义。
- 已保存的名称长度保持在1至40个字符之间。
- 创建时，发送
```
name
```
  和
```
schema
```
  ；仅当有明确需求时，才添加
```
type
```
  、
```
description
```
  、
```
regex
```
  、
```
model
```
  或
```
compliancePlan
```
  。
- 检查时，通过列表过滤器或已验证的ID定位确切资源，然后使用
```
GET /structured-output/{id}
```
  接口。不得通过部分名称猜测。
- 更新时，先读取当前定义，仅发送需要修改的字段。仅当有意更改schema的顶级类型时，才使用
```
schemaOverride=true
```
  ；否则不得使用该参数绕过schema安全机制。
- 修改后重新获取资源并对比请求的字段。仅HTTP状态成功但未返回预期状态时，不能视为验证成功。
安全关联或取消关联。
- 优先使用已保存Structured Output文档中记录的
```
assistantIds
```
  关系进行关联。读取当前的
```
assistantIds
```
  ，精确添加或移除已解析的助手ID，并保留所有无关ID。
- 此操作仅对Structured Output的
```
assistantIds
```
  进行Patch。重新获取Structured Output和助手，验证返回结果中的关系以及助手的
```
artifactPlan.structuredOutputIds
```
  。
- 若实现中需对助手进行Patch，先读取助手信息，发送完整的现有
```
artifactPlan
```
  ，仅修改
```
structuredOutputIds
```
  。保留录音、日志、通话记录、评分卡、存储及其他工件设置。
- 不得声称创建定义时已自动关联；不得声称取消关联会删除定义或移除已存储在过往通话中的结果。
全面执行前先预览。
- 使用
```
POST /structured-output/run
```
  接口，传入一个真实的通话ID并设置
```
previewEnabled: true
```
  。只能传入
```
structuredOutputId
```
  或临时
```
structuredOutput
```
  ，不能同时传入两者。
- 确认所选通话包含代表性证据，且返回值符合schema和业务含义。
- 说明预览操作不会更新通话工件。
- 若提取结果错误，先简化schema或完善描述，再考虑更换模型或自定义提取提示词。
仅在请求时执行或回填。
- 设置
```
previewEnabled: false
```
  或省略该参数以更新通话工件。每次请求传入的通话ID数量不超过当前文档规定的最大值100个。
- 在执行多通话运行前，说明确切的输出内容、通话数量，以及此输出的现有值可能被替换，而其他结构化输出值将保留。
- 仅使用用户提供或通过已验证的公开API查询返回的通话ID。按通话ID报告部分失败情况；不得暗示操作是全有或全无的事务。
检索并验证结果。
- 在正常关联的通话结束后，预留通话后处理时间再检查通话。
- 使用
```
GET /call/{id}
```
  接口检索每个通话，读取
```
call.artifact.structuredOutputs[structuredOutputId].result
```
  。
- 在确认结果准确前，先验证结果是否符合预期schema，并检查代表性的源证据。schema有效性仅证明格式正确，不代表事实准确。
- 分别报告：定义已保存、助手已关联、预览已返回、通话工件已更新、结果已验证。仅提及实际已验证的步骤。

Error Handling

错误处理

On
```
400
```
, inspect the response for schema, regex, model, relationship, or run constraints. Correct one unambiguous documented issue and retry once; never repeat an unchanged request.
On
```
401
```
or
```
403
```
, stop and report authentication or permission failure.
On
```
404
```
, report the missing Structured Output, assistant, or call and identify the exact unresolved ID.
On
```
409
```
, re-read current state before deciding whether the intended relationship or update already exists.
On
```
429
```
or
```
5xx
```
, preserve the request context, report the service condition, and do not claim success.
If a result is absent, distinguish processing delay, missing attachment, disabled artifact storage, insufficient call evidence, and extraction failure before recommending a change.

遇到
```
400
```
错误时，检查响应中的schema、正则表达式、模型、关系或运行约束问题。修正一个明确的文档记录问题后重试一次；不得重复发送未修改的请求。
遇到
```
401
```
或
```
403
```
错误时，停止操作并报告认证或权限失败。
遇到
```
404
```
错误时，报告缺失的Structured Output、助手或通话，并指明确切的未解析ID。
遇到
```
409
```
错误时，先重新读取当前状态，再判断预期的关系或更新是否已存在。
遇到
```
429
```
或
```
5xx
```
错误时，保留请求上下文，报告服务状态，不得声称操作成功。
若结果缺失，先区分处理延迟、关联缺失、工件存储禁用、通话证据不足和提取失败等情况，再建议修改方案。

API Implementation Examples

API实现示例

Read API Examples when implementation code is needed. Use the official TypeScript or Python Server SDK only after confirming the generated method in its current official reference; use direct REST when SDK syntax is unavailable or unstable.

当需要实现代码时，请查阅API示例。仅在确认当前官方参考文档中包含生成的方法后，才使用官方TypeScript或Python Server SDK；当SDK语法不可用或不稳定时，使用直接REST调用。

Output Contract

输出契约

Return only the sections relevant to the request:

Mode: artifact-only, saved definition, relationship change, preview, or artifact-writing run
Assumptions or blocking questions
Final schema and Structured Output configuration
Created or updated resource ID and verified fields, when mutated
Attachment state and preserved relationships, when changed
Preview or execution result, affected call IDs, and whether artifacts changed
Retrieved result plus schema and evidence limitations
Remaining configuration or validation work

仅返回与请求相关的部分：

模式：仅工件、已保存定义、关系变更、预览或写入工件的运行
假设或阻塞问题
最终schema和Structured Output配置
已创建或更新的资源ID及已验证字段（当有修改时）
关联状态和保留的关系（当有变更时）
预览或执行结果、受影响的通话ID，以及工件是否已变更
检索到的结果及schema和证据限制
剩余的配置或验证工作