五分钟发出第一个调用

从零开始，不用离开本页，就能用 API 创建一场进行中的会话。

开始之前

  • 一个付费套餐的账户：API 不属于 FREE（不付费也可以翻阅完整参考）。
  • 工作区里的一份演示文稿：您即将创建的会话要运行一份已有的演示文稿。

  1. 创建您的凭据

    在工作区中打开组织 → API，创建一个带 content:write 权限范围的凭据。密钥只显示一次：请务必保存。

    获取 API 密钥

    凭据属于组织，而不属于您的用户：任何管理员都可以吊销它，每次使用都会记入审计日志。只申请您需要的权限范围，results:read 用于读取，content:write 用于创建和操控。

  2. 创建并开启一场会话

    把密钥放进 X-API-Key 请求头，在一份已有的演示文稿上创建会话，然后开启它。

    curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/sessions \
  -H "X-API-Key: vz_live_…" \
  -d '{ "presentation_id": "prs_8f3k2" }'

curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/sessions/ses_71xw9/open \
  -H "X-API-Key: vz_live_…"

    会话创建出来时是 DRAFT 状态；开启它会生成 join_code，房间随即就绪。留意响应里的 X-RateLimit-* 响应头：它们随每次回复返回，告诉您 60 秒窗口内还剩多少请求额度。

  3. 接收结果

    为 question.results.finalized 注册一个 webhook，在您的后端接收带签名的汇总结果。

    curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/webhooks \
  -H "X-API-Key: vz_live_…" \
  -d '{ "url": "https://example.com/hooks/votinova",
        "event_types": ["question.results.finalized"] }'

    请保存注册时返回的 signing_secret：它只显示一次，也正是它让您能校验每一次投递。Webhook 指南提供了三种语言的校验代码，复制即可用。

如果哪里不对劲

  • 401：缺少 X-API-Key 请求头或相应权限范围，响应体会在 required_scope 里点明是哪一个。
  • 402：您的套餐不含 API，响应体的 upgrade_to 会给出可以解锁它的套餐。
  • 429：本窗口的额度已用完，等待 retry_after_seconds 再按退避策略重试。

接下来做什么？

翻阅完整参考，在线试用每个端点，再通过 MCP 接上 Zapier 或您的智能体。

API 参考 →