调用容器服务

容器服务是托管在你团队代理上的长时运行容器（概念见容器服务，部署流程见部署容器服务）。当服务进入 running 状态后，三个运行时端点可以访问它。全部接受 JWT、sk-、dk- 作为 Bearer 凭证。

服务发现

列出你团队可见的服务：

GET /api/v1/r/containers HTTP/1.1
Authorization: Bearer sk-...

或按 slug 查询单个服务：

GET /api/v1/r/containers/{serviceSlug} HTTP/1.1
Authorization: Bearer sk-...

响应中的关键字段：

字段	含义
`service_slug`	URL 安全的标识。用在代理和 invoke 路径中。
`service_status`	`created`、`deploying`、`running`、`stopping`、`stopped`、`failed` 之一。
`exposed_port`	容器内部监听的端口。
`service_type`	`deployed`（运行在团队代理上）或 `external`（出口到外部 URL）。
`usage_prompt`	可选的面向 AI 代理的自然语言描述。能列出该服务的任何成员都能读到 —— 不要在这里放密钥。
`openapi_url`	可选的、容器上提供 OpenAPI 文档的路径。AI 客户端可在调用前抓取它取得 schema。

透明代理

对于 shell 脚本、原始 HTTP 客户端、以及任何已经能讲容器协议的代码，使用 catch-all 代理：

ANY /api/v1/r/containers/{serviceSlug}/*

slug 之后的路径会原样转发到容器，容器的响应也原样返回。

# vLLM 暴露 OpenAI 兼容 API
curl -H "Authorization: Bearer sk-..." \
  https://core.cyberun.cloud/api/v1/r/containers/my-llm/v1/models

curl -X POST \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3","messages":[{"role":"user","content":"hi"}]}' \
  https://core.cyberun.cloud/api/v1/r/containers/my-llm/v1/chat/completions

由于代理保留了 OpenAI 的请求和响应结构，你可以把任意 OpenAI 兼容 SDK 的 baseURL 直接指向代理：

import OpenAI from 'openai';

const client = new OpenAI({
	apiKey: process.env.CYBERUN_KEY,
	baseURL: 'https://core.cyberun.cloud/api/v1/r/containers/my-llm'
});

const reply = await client.chat.completions.create({
	model: 'llama3',
	messages: [{ role: 'user', content: 'hi' }]
});

任何底层 HTTP 形状与容器暴露的协议匹配的厂商 SDK 都可以用同样的方式。

结构化 invoke（适合 MCP）

对于希望使用单一固定请求形状（而非 catch-all 路径）的程序化客户端和 MCP 调用方：

POST /api/v1/r/invoke/{serviceSlug} HTTP/1.1
Authorization: Bearer sk-...
Content-Type: application/json

{
  "method": "POST",
  "path": "/v1/chat/completions",
  "headers": { "Content-Type": "application/json" },
  "body_base64": "eyJtb2RlbCI6Imxsb..."
}

请求体字段：

字段	必填	含义
`method`	是	HTTP 方法（`GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`）。
`path`	是	容器上的路径，含开头的 `/`。允许查询串。绝对 URL 或协议相对 URL 会被拒绝。
`body_base64`	否	请求体，base64 编码以让二进制数据安全穿过 JSON。`GET` / `DELETE` 可省略。
`headers`	否	要转发的请求头。逐跳头（`Host`、`Connection`、`Upgrade`、`Transfer-Encoding`、`TE`、`Trailer`）服务端会剥离。

响应：

{
  "status_code": 200,
  "headers": { "Content-Type": "application/json" },
  "body_base64": "eyJjaG9pY2VzIjpbey4uLn1dfQ=="
}

/r/invoke/{slug} 单独占用一条路径，而不是 /r/containers/{slug}/invoke —— 这样如果容器自身暴露了 /invoke 端点，它仍然可以通过 catch-all 代理访问。

何时用哪个

场景	用法
shell 脚本、`curl`、OpenAI SDK baseURL 重定向	透明代理
用固定请求形状把服务接进 MCP 工具	结构化 `/r/invoke/`
从非流式调用方转发二进制负载	结构化 `/r/invoke/`

状态码

两个端点都会在请求到达容器之前用这些代码暴露网关层错误：

状态码	含义
`400`	服务未处于 `running` 状态（仍在 `created`、`deploying`、`stopping`、`stopped` 或 `failed`）。
`404`	此团队中找不到该 service slug。
`502`	代理或网关隧道与容器通信时返回错误。
`503`	服务正在运行但不可用 —— 没有健康实例,或没有在线代理能访问它。

其他状态码都是容器自己返回的。

概览

指南

端点

调用容器服务

服务发现

透明代理

结构化 invoke（适合 MCP）

何时用哪个

状态码

相关

​服务发现

​透明代理

​结构化 invoke（适合 MCP）

​何时用哪个

​状态码

​相关

服务发现

透明代理

结构化 invoke（适合 MCP）

何时用哪个

状态码

相关