跳到内容
Skynet文档
页面

集成

API

通过 HTTP API 进行身份验证、启动运行并读取结果。

Skynet HTTP API 让脚本和工具能够做到 Web 应用能做的事:启动运行、观察运行并读取结果。本页介绍如何为请求签名、完整参考文档在哪里,并提供一个完整示例。

基础 URL

把每个请求发送到:

https://api.skynetml.com

身份验证

API 使用 API 令牌。

  1. 在 Skynet 中打开 设置,然后打开 API 标签页。
  2. 点击 生成令牌。
  3. 立即复制令牌。Skynet 只会显示一次完整令牌。

在每个请求的 Authorization 请求头中发送令牌:

Authorization: Bearer skyd_...
  • 令牌以 skyd_ 开头。
  • 每个用户最多只有一个有效令牌。生成新令牌会使旧令牌失效。
  • 点击 吊销令牌 可使令牌失效。

交互式参考文档

完整参考文档位于 api.skynetml.com/scalar。它列出了每个公开端点、其字段和响应。你可以在该页面发送测试请求。

参考文档读取的是位于 https://api.skynetml.com/openapi.public.json 的 OpenAPI 文档。你可以用这个文件为你的语言生成客户端。

主要端点

方法和路径作用
GET /models列出你可以使用的模型。
GET /optimizers列出适合某个设置的优化器。
GET /blackbox/engines列出原生引擎以及每个引擎是否可用。
POST /optimize为提示词、代码、文本或 DSPy 程序启动运行。
POST /blackbox/run在 GitHub 仓库上启动运行。
GET /optimizations列出你的运行。
GET /optimizations/{optimization_id}返回一次运行:状态、进度、日志和结果。
GET /optimizations/{optimization_id}/artifact返回运行找到的最佳版本。
POST /optimizations/{optimization_id}/cancel停止一次运行。
POST /serve/{optimization_id}在新输入上运行最佳版本。
GET /health显示服务是否正常运行。

启动运行

POST /optimize 接受与提交向导相同的设置。本示例改进一个把客服消息归类到标签的提示词。

curl https://api.skynetml.com/optimize \
  -H "Authorization: Bearer $SKYNET_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-labels-001" \
  -d @run.json

重要字段:

  • task.artifact.kind 取值为 prompt、code、text 或 dspy_program。
  • data.mode 取值为 pairs(带期望输出的输入)或 single(恰好一个用例)。
  • optimizer.choice 取值为 auto,或 GET /optimizers 返回的某个优化器名称。
  • max_cost_cents 是本次运行的支出上限,单位为美分。
  • is_private 默认为 false。设为 true 可将运行设为私有。

关于 run_code 和 metric_code 的规则,请阅读指标与评分器。

响应

状态码含义
201Skynet 已将运行加入队列。响应体包含 optimization_id 和 status。
202设置检查仍在进行。等待 Retry-After 请求头中给出的秒数,然后用相同的 Idempotency-Key 发送相同的请求体。
402你的余额不足。
409你达到了配额,或者设置检查已过期。
422请求或工作区代码与优化器不匹配。

观察运行

轮询运行,直到其状态变为最终状态:

curl https://api.skynetml.com/optimizations/$RUN_ID \
  -H "Authorization: Bearer $SKYNET_TOKEN"

status 字段的取值为以下之一:

状态最终状态
pending、validating、running否
paused否
success是
failed、cancelled、stopped是

每 10 到 30 秒轮询一次。一次运行可能需要几分钟到几小时。

API 参考文档列出了运行响应的每个字段。

使用结果

当状态为 success 时,获取最佳版本:

curl https://api.skynetml.com/optimizations/$RUN_ID/artifact \
  -H "Authorization: Bearer $SKYNET_TOKEN"

要在新输入上运行最佳版本,请发送 POST /serve/{optimization_id}。关于每个分数的含义,请阅读结果。

限制

API 使用与 Web 应用相同的配额、速率限制和计费方式。请阅读限制和计费。