Convilyn 使用手册

API 密钥

API 密钥让另一个应用——Ainalyn 桌面应用、命令行，或你自己的集成——代表你的 Convilyn 账户进行操作。你可以在网页版的 设置 → API，或完整的 API 控制台中管理密钥。

API 密钥的用途

密钥会对代表你发出的调用进行身份验证，让你能够在浏览器之外使用 Convilyn：

  • Ainalyn 桌面应用——粘贴密钥即可将应用连接到你的账户（参见 Convilyn 与 Ainalyn）。
  • 命令行——convilyn CLI 会从你的环境中读取密钥。
  • 你自己的集成——任何调用 Convilyn API 的脚本或服务。

密钥代表你进行操作，因此请像对待密码一样对待它。 任何持有它的人都可以花费你的点数。

创建密钥

  1. 打开 设置 → API（请先登录）。
  2. 选择 创建密钥，并给它一个日后能认出的名称——例如「我的桌面」。
  3. 选择密钥的范围 (scopes)，并可选择性设置到期日 (expiry)（两者均在下方说明）。默认为完整访问、永不过期，适合个人密钥。
  4. 复制完整密钥。它以 ck_ 开头，并且只显示一次——请妥善保存，因为之后将无法再次查看。

范围

范围会限制密钥可执行的操作：

  • 读取 (Read)——只读访问：列出工作流、查询状态、下载结果、查看用量。
  • 写入 (Write)——运行会消耗点数的工作流。

新密钥默认为完整访问（读取＋写入）。若密钥仅用于报表或只读自动化，可只选 读取——它无法消耗点数，因此即使泄露也无法产生费用。

到期

可为密钥设置可选的到期日。一旦超过，密钥会自动停止验证。留空表示密钥永不过期。

使用密钥

将密钥作为 Bearer 令牌放在 Authorization 请求头中发送：

curl https://convilyn.corenovus.com/api/v1/workflows/catalog \
  -H "Authorization: Bearer ck_your_key"

将 ck_your_key 替换为你创建的密钥。完整的编程接口——Python SDK、convilyn CLI 和 REST API——请参见开发者文档。

管理你的密钥

你可以在 设置 → API 中：

  • 轮换密钥——签发一个新的密钥，同时让旧密钥在短暂的宽限期内（24 小时）继续工作，方便你无中断地切换到新密钥。宽限期过后，旧密钥会自动停用。
  • 吊销单个密钥——它会立即停止工作，且无法撤销。
  • 全部吊销——当你怀疑密钥泄露时的事件响应控件。

监控使用情况

系统会追踪每个密钥的活动，方便你掌握费用与状态：

  • 用量——每个密钥的请求数、错误数和已用点数，可选预设或自定义时间范围。
  • 请求日志——查看近期的 API 调用（方法、端点、状态、耗时、费用）。
  • 速率限制——各端点类别对每个密钥强制执行的请求上限。

套餐与可用性

API 访问是 Business 套餐的功能，目前向所有已登录用户开放。使用密钥发出的云端调用，与网页版共用同一个点数余额。

Webhook

注册一个 HTTPS 端点，Convilyn 会在任务完成时向它发出 POST，让你的集成无需轮询即可对结果做出响应。

  • 事件——job.completed 和 job.failed。
  • 签名——每次投递都带有 X-Convilyn-Signature 头（对内容做 HMAC-SHA256），让你的接收端能验证它确实来自 Convilyn。签名密钥只会在你创建 hook 时显示一次。
  • 可靠——投递失败会以指数退避重试，多次失败后移入死信队列 (dead-letter queue)。投递与你的任务彼此隔离，因此接收端缓慢或失败都不会拖慢任务本身。
  • 可测试——可向 hook 发送一条示例事件，在正式依赖前先验证你的端点。

在 API 控制台中创建与管理 webhook——显示密钥、启用或停用 hook，或发送测试事件。

API 控制台

如需完整的管理界面，请使用独立的 API 控制台——用你的 Convilyn 账户登录。它把上述所有功能集中在一处，并提供更深入的视图：

  • 密钥——创建、轮换、撤销；设置范围与到期日。
  • 用量——可用预设或自定义时间范围的分析，并含每个密钥的细分。
  • 请求日志——逐页浏览近期的 API 调用。
  • 速率限制——各端点类别对每个密钥的上限。
  • Webhook——注册、测试与管理对外的 webhook。

网页版的 设置 → API 是核心功能的快速视图（密钥、用量与桌面应用）；控制台则是完整体验。

接下来