开始使用 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_KEY="sk-coasty-test-your_key_here"使用 `POST /v1/runs` 启动任务，替换示例中的 `machine_id`，在 `task` 中描述任务结果，并发送 `Idempotency-Key` 以确保重试时不会启动重复的任务。创建任务的响应初始状态为 `queued`，Coasty 随后会驱动机器，记录每个步骤，最终任务状态可能为 `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` 头，格式为 `t=<unix_ts>,v1=<hex>`。
要验证签名，将签名负载构建为 `"<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
工作流 DSL（`dsl_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}` 调整 TTL，`ttl_minutes` 从当前时间开始计算（也可作为租赁延长），支持 5 - 10080 分钟（5 分钟到 7 天），`0` 表示取消自动销毁。其他值会返回 `400 INVALID_TTL`。配置时不设置 TTL 也可以，但响应头会提示你设置。
运行时计费方面，机器按分钟向开发者 API 钱包计费（与任何订阅信用分开），费用向下取整为整数信用。运行中的 Linux 机器每小时 $0.05，运行中的 Windows 机器每小时 $0.09，`stopped` 或 `suspended` 状态的机器每小时 $0.01，`creating`、`error` 和 `terminated` 状态不计费。过渡状态（`starting`/`stopping`/`restarting`）按运行费率计费。按调用的控制端点（操作、终端、文件、浏览器、截图、连接）不计费，仅收取运行时费用。
如果 API 钱包在机器运行时耗尽，下一次扫描会停止机器（状态变为 `suspended`），而不是销毁它，磁盘和快照会保留。充值钱包后使用 `POST /start` 恢复运行。可以通过 `GET /v1/billing/active` 实时查看每个计费机器的费用累积情况。
连接与控制
在 18 个支持保留和重放的操作中，发送原始请求时带上 `Idempotency-Key`。使用相同密钥重试会重放存储的结果，不会重复计费，不支持的操作无法事后获得幂等性。