Coasty API 全解析：从任务运行到机器配置，掌握自主工作流与控制方法

开始使用 Coasty API在托管机器上运行自主任务将它们组合成工作流仅在需要直接控制时使用预测原语。你可以从任务运行、工作流和机器开始仅当应用程序需要控制循环时才使用预测原语。认证方面每个计费调用在模型运行前收费若失败则自动退款X-Credits-Refunded 头可确认退款。所有使用 API 密钥认证的请求都必须包含密钥。四个健康检查是公开的Webhook 入口使用文档中记录的 Coasty-Signature HMAC 凭证。对于 API 密钥操作标准形式是 X-API-Key 头但 Authorization: Bearer key 也可以空的 X-API-Key 会回退到 Bearer 头。选择一种形式并发送原始密钥不要在 X-API-Key 中粘贴 Bearer 这是新手最常犯的错误会返回 401 INVALID_API_KEY。密钥可从 [API 密钥](/developers/keys) 页面创建和撤销要像对待密码一样对待密钥将其保存在服务器端存储在环境变量中切勿在客户端代码中提交或使用。有两种密钥前缀sk-coasty-live- 为正式运行真实模型并扣除美元钱包余额sk-coasty-test- 为测试返回模拟响应不产生费用适用于本地开发和持续集成。建议在集成时使用测试密钥sk-coasty-test- 密钥不会产生费用且针对模拟虚拟机运行但请求和响应的格式与正式环境相同其 X-Credits-Charged 和 usage.cost_cents 始终为 0这样可以在切换到正式密钥之前自信地构建和运行持续集成。运行第一个任务需要 API 密钥和一台机器。从 [API 密钥](/developers/keys) 页面获取测试密钥不会产生费用然后使用现有机器或配置一台新机器。在 shell 中设置密钥export COASTY_API_KEYsk-coasty-test-your_key_here使用 POST /v1/runs 启动任务替换示例中的 machine_id在 task 中描述任务结果并发送 Idempotency-Key 以确保重试时不会启动重复的任务。创建任务的响应初始状态为 queuedCoasty 随后会驱动机器记录每个步骤最终任务状态可能为 succeeded、failed、cancelled 或 timed_out。应用程序可以轮询、订阅事件流或接收签名 Webhook无需自行执行每个预测。任务运行使用 POST /v1/runs 提交任务和机器Coasty 会为你运行整个循环通过 SSE 流式传输事件在生命周期变化时调用 Webhook并在需要时暂停等待人工干预。一个任务运行会将任务和机器交给智能体然后由其自主执行直到完成。智能体自主循环验证自身工作通过或失败遇到困难时可暂停等待人工干预每个完成步骤收费 $0.05旧版 v1 引擎为 $0.08/步并实时流式传输每个事件。只需发起一次调用并监控无需自行运行预测循环。使用 POST /v1/runs 创建任务两个必需字段是 machine_id 和 task响应是一个 agent.run 对象状态为 queued还有一个一次性的 webhook_secret 用于验证 Webhook。发送 Idempotency-Key 头可确保重试安全。任务运行字段包括 machine_id、task、cua_version 等多个字段每个字段都有其是否必需和具体描述。任务运行端点有 POST /v1/runs、GET /v1/runs 等多个每个端点有其用途。任务会从 queued 状态进入 running 状态可能在 running 和 awaiting_human 之间切换最终以 succeeded、failed、cancelled 或 timed_out 结束。终止状态是不可变的因此一旦到达终止状态停止轮询是安全的。任务运行需要 runs:read 和 runs:write 权限新密钥默认具备这些权限。流式事件GET /v1/runs/{id}/events 返回一个 Server-Sent Events 流可实时跟踪任务运行而无需轮询。每个事件有一个类型和一个数字 id序列号。如果连接中断重新连接并通过发送最后看到的序列号作为 Last-Event-ID 头或 ?after 查询参数来重播错过的事件。流在 done 事件后关闭。事件类型包括 status、text、reasoning 等多种每种事件有其含义。人工接管有些步骤需要人工干预例如验证码、一次性代码或判断决策。当智能体遇到此类情况且 on_awaiting_human 设置为 pause 时任务状态变为 awaiting_human并发出 awaiting_human 事件及原因。人工完成阻塞步骤在同一机器会话中后使用 POST /v1/runs/{id}/resume 和可选的 note 交回控制权。仅在状态为 awaiting_human 时恢复操作才有效。可以从任务对象status awaiting_human 且 awaiting_human_reason 有值、SSE awaiting_human 事件或 run.awaiting_human Webhook 检测到暂停。恢复后任务回到 running 状态并发出 resumed 事件。如果希望任务在需要人工干预时停止而不是等待可以在创建时将 on_awaiting_human 设置为 fail 或 cancel。Webhook创建任务时传递 webhook_url仅支持 HTTPS会在每个生命周期转换时 POST 一个签名回调。创建调用的响应中会包含一次 webhook_secret请保存它因为每个回调都使用它进行签名。每个请求都携带一个 Coasty-Signature 头格式为 tunix_ts,v1hex。要验证签名将签名负载构建为 t. raw_request_body使用 webhook_secret 作为密钥计算 HMAC-SHA256 哈希值并与 v1 进行常量时间比较。始终对原始请求体字节进行哈希处理在任何 JSON 重新序列化之前。Webhook 事件包括 run.awaiting_human、run.succeeded 等多种每种事件有其含义。自带模型BYOK默认情况下计算机使用框架中的每个大语言模型LLM调用都在 Coasty 管理的模型上运行。BYOK自带密钥则改变了这一方式选择启用后整个框架工作者、定位、代码智能体和压缩每个 LLM 调用将在你自己的 Anthropic 或 OpenAI 账户上运行。启用 BYOK 始终需要明确选择可按请求或按存储的密钥进行。provider: managed或完全省略 llm将保持平台默认设置不变。有两种方式提供密钥可以使用 PUT /v1/llm/keys/{provider} 一次性存储密钥在存储时使用 AES-256-GCM 加密仅会返回 sha256 前缀的指纹也可以在每个请求的头中发送密钥。头中的密钥优先级高于存储的密钥。发送没有提供者的密钥将返回 422。BYOK 请求头包括 X-LLM-Provider、X-LLM-Api-Key 等每个头有其是否必需和含义。这些请求头适用于 POST /v1/predict、POST /v1/runs 等多个操作。存储的密钥通过三个端点进行管理需要 llm_keys 权限新的正式密钥默认具备此权限。这些端点需要正式密钥沙盒密钥无法读取、覆盖或删除生产凭证存储。自带模型端点有 PUT /v1/llm/keys/{provider}、GET /v1/llm/keys 等每个端点有其用途。请求体中相同的端点接受一个 llm 对象用于选择提供者和可选的每个框架角色的模型。该对象故意没有 api_key 字段尝试使用会返回 422密钥只能通过头或加密存储传递这样它们就不会在运行对象、Webhook 或幂等重放中被返回。使用 BYOK 时Coasty 的按调用和按步骤的平台费用不变模型令牌费用由自己的提供者账户直接收取。工作流工作流是一个小型的 JSON DSL控制步骤如 if / loop / parallel / human_approval是纯函数且安全的每个任务步骤作为一个真实的运行执行有自己的计费和事件。工作流将多个运行组合成一个版本化的程序支持分支、循环和条件控制并通过 JSON DSL 表达。每个 task 步骤本身是一个智能体运行因此工作流是链接任务、根据条件进行控制和在任务之间传递结果的方式。工作流是版本化的重新创建相同的 slug 会增加版本号使用 PUT 操作也会如此。工作流端点有 POST /v1/workflows、GET /v1/workflows 等每个端点有其用途。工作流需要 workflows:read 和 workflows:write 权限新密钥默认具备这些权限。完整的步骤和条件目录请参阅工作流 DSL。工作流 DSL工作流 DSLdsl_version 为 2026-06-01是一个 JSON 对象包含一个 steps 数组和一个可选的 output。每个步骤有一个 id 和一个 type。task 步骤运行智能体并将其结果{ status, passed, result, run_id, steps, error }绑定到 save_as 名称和步骤 id 下以便后续步骤可以读取。步骤类型包括 task、assert、if 等多种每种步骤类型有其格式和描述。条件运算符包括 eq / ne、lt / gt / lte / gte 等多种每种运算符有其格式和描述。工作流运行有三个硬限制budget_cents美元美分的花费上限0 表示无限制、max_iterations循环上限和 deadline_seconds时钟时间。超过限制会导致工作流以 failed 或 timed_out 结束。定义在被接受之前会进行验证以下限制在创建和临时运行时强制执行无效的定义将被拒绝并返回 422 VALIDATION_ERROR而不是在运行中失败。工作流定义限制包括最大步骤数、最大嵌套深度等多个方面。工作流是版本固定的。当运行开始时工作流的当前 definition 会被快照到该运行中因此编辑或替换工作流会增加其 version不会影响正在运行的任务。每个运行会记录其执行的 workflow_version。运行工作流使用 POST /v1/workflows/{id}/runs 启动已保存的工作流或使用 POST /v1/workflows/runs 直接运行定义无需保存只需在请求体中添加 definition和可选的 inputs_schema。两者都返回一个 workflow.run 对象。请求体接受 inputs、任务步骤的默认 machine_id 以及 budget_cents、max_iterations 和 deadline_seconds 限制。这里也支持 Idempotency-Key 头。工作流运行端点有 POST /v1/workflows/{id}/runs、POST /v1/workflows/runs 等每个端点有其用途。工作流运行对象字段包括 id、object、status 等多个每个字段有其类型和描述。机器配置机器是 Coasty 管理的云虚拟机智能体可以查看和控制。可以配置一台机器轮询直到其状态变为 running然后将其交给任务运行智能体驱动完成任务或使用操作端点自行控制。机器是可选的/predict、/sessions 和 /ground 操作可以在自己的屏幕上运行。只有当希望智能体在 Coasty 托管的虚拟机上执行时才需要使用 Coasty 机器。使用 POST /v1/machines 配置机器只有 display_name 是必需字段其他字段都有合理的默认值。请求体不接受未知字段因此拼写错误会返回 422 VALIDATION_ERROR而不是被默默忽略。机器配置字段包括 display_name、os_type、desktop_enabled 等多个每个字段有其类型、默认值和备注。配置是异步的响应会立即返回机器状态为 creating并包含一个 connection 对象其秘密信息会被屏蔽。此时虚拟机还不可用需要轮询 GET /v1/machines/{id} 直到状态变为 running 后再发送操作或启动任务。机器对象字段包括 id、display_name、status 等多个每个字段有其类型和描述。使用 GET /v1/machines 列出机器最新的在前?limit 范围 1 - 200默认 50返回 { data, has_more, request_id }。使用 GET /v1/machines/{id} 获取单个机器。这两个操作直接从注册表读取因此即使在配置繁忙时也能正常工作。配置正式机器需要 machines:write 权限钱包余额至少为 20 信用无限制层级的密钥可跳过此要求并且计划有并发机器数量限制。开发时sk-coasty-test- 密钥会返回完全形状的模拟虚拟机ID 为 mch_test_…is_test: true不产生计费最多同时支持 5 台。机器生命周期与 TTL机器在存在期间按分钟计费资金不足时会停止不会销毁设置 TTL 可在 created_at ttl_minutes 时自动销毁虚拟机。机器状态包括 creating、running、starting 等多种每种状态有其计费情况和含义。启动、停止和重启操作分别通过 POST /v1/machines/{id}/start、/stop 和 /restart 进行这些操作是异步的调用会返回过渡状态starting / stopping需要轮询直到状态稳定。这些操作会检查状态例如启动正在运行的机器或停止未运行的机器会返回 409 INVALID_STATE并在请求体中包含 current_state 和 allowed_from以便做出正确反应。start 操作允许从 stopped 或 error 状态开始stop 操作仅允许从 running 状态开始。使用 DELETE /v1/machines/{id} 终止机器这是永久操作虚拟机会被销毁后续 GET 请求返回 404 MACHINE_NOT_FOUND。删除操作是幂等的删除已不存在的机器仍然会成功因此重试是安全的。自动销毁TTL方面运行中的机器会一直计费直到你销毁它因此可以设置 ttl_minutes 作为安全措施。后台扫描约每 60 秒一次会在 auto_destroy_at 时间过后终止机器。可以随时使用 PATCH /v1/machines/{id} 调整 TTLttl_minutes 从当前时间开始计算也可作为租赁延长支持 5 - 10080 分钟5 分钟到 7 天0 表示取消自动销毁。其他值会返回 400 INVALID_TTL。配置时不设置 TTL 也可以但响应头会提示你设置。运行时计费方面机器按分钟向开发者 API 钱包计费与任何订阅信用分开费用向下取整为整数信用。运行中的 Linux 机器每小时 $0.05运行中的 Windows 机器每小时 $0.09stopped 或 suspended 状态的机器每小时 $0.01creating、error 和 terminated 状态不计费。过渡状态starting/stopping/restarting按运行费率计费。按调用的控制端点操作、终端、文件、浏览器、截图、连接不计费仅收取运行时费用。如果 API 钱包在机器运行时耗尽下一次扫描会停止机器状态变为 suspended而不是销毁它磁盘和快照会保留。充值钱包后使用 POST /start 恢复运行。可以通过 GET /v1/billing/active 实时查看每个计费机器的费用累积情况。连接与控制在 18 个支持保留和重放的操作中发送原始请求时带上 Idempotency-Key。使用相同密钥重试会重放存储的结果不会重复计费不支持的操作无法事后获得幂等性。