HTTP API 参考

当你的服务无法使用 Python SDK 时，可以直接调用 HTTP API。在交互式终端中，优先使用 CLI管理鉴权、输出和资源操作。

业务作业统一使用 /v1/job：提交时设置 type=agent|sandbox|train|inference（省略为 agent），训练列表使用 ?type=train。详情与结果使用 job_id，训练专属字段在 training 中；停止为 POST /v1/job/{job_id}/stop。旧 jobs/train/sessions API 已移除，客户端与平台须配套升级。协议原生 create_session/session_id 仅限协议适配器。

地址与鉴权

用途	地址	鉴权方式
官网与产品介绍	`https://envloop.ai`	公开页面
网页控制台	`https://console.envloop.ai`	浏览器登录
CLI、SDK 与资源 API	`https://api.envloop.ai`	Bearer API Key
OpenAI 兼容推理	`https://api.envloop.ai/v1/job/YOUR_JOB_ID/Inference`	有权限的项目密钥以及就绪的端点
兼容训练 SDK 协议	`https://api.envloop.ai/v1/job/tinker`	通过 `TINKER_CREDENTIAL_CMD` 提供项目密钥

按认证指南在控制台创建项目密钥。通过终端的隐藏输入或服务的密钥管理器设置 ENVLOOP_API_KEY。不要把密钥放进网页 URL 或前端构建文件。

curl --fail-with-body --silent --show-error \
  https://api.envloop.ai/v1/me \
  -H "Authorization: Bearer $ENVLOOP_API_KEY"

成功响应可以确认密钥代表的身份与允许的作用域。浏览器会话和 API Key 是不同凭据。本文列出一个接口，并不代表所有密钥都能调用它。仅允许真人账户执行的管理操作需要登录控制台，项目操作还会检查资源归属与凭据能力。

工作区与项目上下文

配置了上下文后，SDK 会发送 X-Workspace-ID 和 X-Project-ID。直接调用 HTTP 时也可以设置相同的请求头：

curl --fail-with-body --silent --show-error \
  'https://api.envloop.ai/v1/job?limit=10' \
  -H "Authorization: Bearer $ENVLOOP_API_KEY" \
  -H "X-Workspace-ID: $ENVLOOP_WORKSPACE_ID" \
  -H "X-Project-ID: $ENVLOOP_PROJECT_ID"

填写当前所选工作区和项目的实际 ID，不要填写显示名称。请求头用于选择上下文，不能扩大密钥权限。切换项目时检查环境变量，避免沿用另一个项目的值。省略上下文时，以平台实际解析出的结果为准，不要假定选中了某个项目。

按功能查找资源接口

以下路径都相对于资源 API 地址。花括号内是占位标识符，普通 ID 路径参数需要 URL 编码；Dataset 和 Profile 的逻辑名称需要先将 UTF-8 字节转换为不带填充符的 base64url。例如 team/data 不能直接作为路径片段，也不能只替换为百分号编码。建议使用 SDK 处理名称编码。请求体和经过核对的示例见对应指南或 SDK 方法，不要根据控制台显示文字猜测字段。

资源	主要路径	使用指南
身份与当前上下文	`/v1/me`；`/v1/session-context` 仅供浏览器账户上下文使用	连接并验证身份
Jobs	`/v1/job`、`/v1/job/{job_id}`、`/v1/job/{job_id}/result`	提交、检查与停止运行
Job 评测快照	`/v1/job/{job_id}/leaderboard`	查看聚合结果
Trials	`/v1/trials`、`/v1/trials/{trial_id}`，以及 Trial 下的 `/detail`、`/logs`、`/result`	检查一次尝试
Trial 产物	`/v1/trials/{trial_id}/artifacts`，以及文件内容与下载接口	读取输出文件
Datasets	`/v1/datasets`、`/v1/datasets/{encoded_name}/versions`，以及版本的任务列表	选择数据集版本
Profiles	`/v1/profiles`，以及详情、版本和默认版本接口	复用执行参数
Checkpoints	`/v1/job/checkpoints`、`/v1/job/checkpoints/{checkpoint_id}`、`…/ttl`、`…/visibility`、`/v1/job/checkpoints/copy`、`/v1/job/checkpoints/usage`，以及下载接口	保存、检查与恢复
Serving Profiles	`/v1/serving/profiles`	选择受支持的推理模板
Adapters	`/v1/adapters`、`/v1/adapters/{adapter_id}`	注册训练权重
Endpoints	`/v1/endpoints`、`/v1/endpoints/{endpoint_id}`，以及事件和操作接口	部署、暂停与恢复推理
清理操作	`/v1/projects/{project_id}/cleanup-operations`、`/v1/projects/{project_id}/operations/{operation_id}`，以及重试接口	跟踪异步清理
临时资源作用域	`/v1/projects/{project_id}/temporary-resource-scopes`，以及详情和 retain 接口	保留指定训练产物
Billing	`/v1/billing/account`、`/ledger`、`/prices`、`/usage`，以及工作区账单接口	理解用量与费用
工作区与项目	`/v1/workspaces`，以及工作区项目列表与项目详情（浏览器账户操作）	选择与管理上下文
成员与邀请	工作区 members/invitations，以及项目 members/member-candidates 接口	管理访问权限
项目凭据	项目 `/api-keys` 与 `/service-accounts` 接口	管理密钥和机器身份
项目限制	项目 `/limits` 接口	了解资源限制

训练仅支持托管 Job：client.training_jobs.models() 查询配方，client.training_jobs.submit(request) 提交；公开交互式训练完全退役，见迁移。

托管发现：GET /v1/job/training-models 返回项目可见的已配置配方、冻结 revision、模态、features/limits（labels、父 checkpoint、超参范围、loss 掩码、序列长度）与请求 schema。type=train Job 返回准入时的 labels、实际 hyperparameters、parent_checkpoint，成功后返回 checkpoint.path，见 Qwen3.8-27B 选项。readiness=configured 不保证准入或 GPU 容量。退役交互路由返回 410 INTERACTIVE_TRAINING_REMOVED；Job/checkpoint/history 与正常 inference 保留原权限。

读取已有结果

curl --fail-with-body --silent --show-error \
  "https://api.envloop.ai/v1/job/$JOB_ID/result" \
  -H "Authorization: Bearer $ENVLOOP_API_KEY" \
  -H "X-Workspace-ID: $ENVLOOP_WORKSPACE_ID" \
  -H "X-Project-ID: $ENVLOOP_PROJECT_ID"

提交成功后立即记录资源 ID，再以合理间隔和明确截止时间轮询该资源。接受提交不代表执行、评分、checkpoint 上传或部署已经结束，各资源状态的含义见对应指南。

创建 Job 遇到网络响应不确定时，可以通过 SDK 或提交契约中的 request_id 找回同一次请求。只有请求意图不变时才复用它；改变实验参数需要新 ID。重试写操作前先读取已有资源，不要在等待就绪时反复创建端点或训练任务。

分页与下载

列表接口可能返回后续游标。保留原有过滤条件，将返回的游标用于下一页；没有后续游标时结束。单页结果不等于全部资源。字段名和条数限制按资源区分，使用对应 CLI 帮助或 SDK 方法，不要假定所有列表响应结构相同。

下载文件时优先使用 SDK/CLI 提供的方法。签名下载链接会过期，并且自身带有访问凭据。直接处理存储重定向时，不要向存储域名转发平台 Bearer 密钥或上下文请求头。如果返回了文件大小或 hash，应进行核验；链接过期时重新请求下载地址。

处理错误

响应	先检查什么	下一步
`400` / `422`	请求字段、ID 格式和选项是否受支持	修正请求，重复发送相同错误请求无助于恢复
`401`	密钥缺失、过期、撤销或 API 地址错误	用 `/v1/me` 验证并更新保存的配置
`403`	密钥能力、项目角色或仅允许真人执行的操作	使用具备权限的身份，上下文请求头不能提权
`404`	资源 ID、项目上下文、删除状态或可见性	在同一项目确认资源后再考虑创建替代资源
`409`	并发修改、状态冲突或前置条件不满足	刷新资源，再针对当前状态执行操作
`429`	频率限制以及响应中的重试提示	在明确截止时间内退避重试
`5xx` / 超时	暂时性服务错误或运行仍在处理中	重试写操作前读取已有资源，保留请求和资源 ID

请求帮助时提供 UTC 时间、方法与路径、HTTP 状态、错误码及相关资源或请求 ID。移除 Authorization 请求头、签名 URL 和私有任务内容。详见故障排查。

下一步

CLI 参考 · Python SDK 参考 · 推理端点 · 客户端配置

地址与鉴权​

工作区与项目上下文​

按功能查找资源接口​

读取已有结果​

分页与下载​

处理错误​

下一步​