gcbps API 调用¶
GC-VIP 用户可以通过外部 API 运行自己云盘内或已经购买的 gcbps。API 密钥只会在生成时完整显示一次,请像保存密码一样妥善保存,不要写入公开仓库、聊天记录或客户端安装包。
准备工作¶
- 在账号资料中生成 API 密钥。密钥以
gcak_开头。 - 确认账号的 GC-VIP 处于有效状态。
- 准备要运行的
gcbpsId。你可以先列出可运行来源,也可以使用已经保存的 ID。 - 如果自动化包含公开输入变量,先读取变量清单,再按照变量名称和类型提交数据。
请求时可以使用以下任一认证请求头:
接口一览¶
| 用途 | 方法和路径 |
|---|---|
| 列出可运行来源 | GET /api/external/gcbps/sources |
| 读取公开变量 | GET /api/external/gcbps/manifest |
| 上传图片、视频或文件变量 | POST /api/external/gcbps/input-files |
| 创建运行任务 | POST /api/external/gcbps/runs |
| 列出运行任务 | GET /api/external/gcbps/runs |
| 查询运行状态 | GET /api/external/gcbps/runs/{jobId} |
| 下载输出文件 | GET /api/external/gcbps/artifacts/{artifactId}/download |
调用流程¶
- 调用
sources获取当前密钥可以运行的来源,或者直接使用已知的gcbpsId。 - 调用
manifest读取公开变量名、变量类型和输入要求。 - 如果变量需要图片、视频或文件,先上传到
input-files并保存返回的inputId。 - 调用
runs创建任务。任务会消耗当前账号的 token 和 G币。 - 使用返回的
jobId轮询任务状态。如果本地丢失了jobId,可以通过任务列表查询最近任务。 - 任务完成后,使用任务结果中的输出信息下载文件。
curl 示例¶
下面的命令依次展示列出来源、上传输入文件、创建任务和查询最近任务。
API_KEY="gcak_..."
BASE="https://ghostclickai.com/api"
curl -H "Authorization: Bearer ${API_KEY}" \
"${BASE}/external/gcbps/sources"
curl -H "Authorization: Bearer ${API_KEY}" \
-F "fieldName=cover" \
-F "file=@cover.png;type=image/png" \
"${BASE}/external/gcbps/input-files"
curl -H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{"gcbpsId":"你的gcbpsId","estimatedMinutes":5,"variables":{"prompt":"hello"}}' \
"${BASE}/external/gcbps/runs"
curl -H "Authorization: Bearer ${API_KEY}" \
"${BASE}/external/gcbps/runs?status=queued&limit=20"
Python 示例¶
下面的示例使用账号云盘里的 gcbpsId 创建运行任务,并在任务完成后下载可用的输出文件。
import requests
api_key = "gcak_..."
base = "https://ghostclickai.com/api"
headers = {"Authorization": f"Bearer {api_key}"}
manifest = requests.get(
f"{base}/external/gcbps/manifest",
headers=headers,
params={"gcbpsId": "你的gcbpsId"},
timeout=30,
).json()
with open("cover.png", "rb") as cover:
uploaded = requests.post(
f"{base}/external/gcbps/input-files",
headers=headers,
data={"fieldName": "cover"},
files={"file": ("cover.png", cover, "image/png")},
timeout=120,
).json()
run = requests.post(
f"{base}/external/gcbps/runs",
headers=headers,
json={
"gcbpsId": "你的gcbpsId",
"estimatedMinutes": 5,
"variables": {"prompt": "hello"},
"inputFiles": [
{
"name": "cover",
"inputId": uploaded["inputFile"]["inputId"],
}
],
},
timeout=30,
).json()
print(manifest["manifest"]["publicVariableSchema"])
job_id = run["job"]["jobId"]
print(job_id, run["job"]["status"])
recent = requests.get(
f"{base}/external/gcbps/runs",
headers=headers,
params={"status": "queued", "limit": 20},
timeout=30,
).json()
print([item["jobId"] for item in recent["jobs"]])
latest = requests.get(
f"{base}/external/gcbps/runs/{job_id}",
headers=headers,
timeout=30,
).json()
for artifact in latest.get("artifacts", []):
if not artifact.get("downloadAvailable"):
continue
content = requests.get(
f"{base}{artifact['downloadPath']}",
headers=headers,
timeout=120,
).content
with open(artifact["fileName"], "wb") as output:
output.write(content)
常见错误¶
| 状态码 | 含义 | 检查方法 |
|---|---|---|
401 | 密钥无效 | 检查是否传入密钥、密钥是否完整、密钥是否已经停用,以及账号状态是否可用。 |
403 | 会员权限不足 | 检查当前账号是否具有有效的 GC-VIP。 |
404 | 资源不存在 | 检查 gcbps、任务或输出文件是否存在,以及它是否属于当前密钥对应的账号。 |
409 | 状态冲突 | 当前任务状态不允许该操作,或者输入文件已经被使用。 |
413 | 容量不足 | 上传文件过大,或者临时缓冲容量不足以接收本次输入。 |
422 | 参数不合法 | 检查 gcbpsId、公开变量、输入文件字段和预估运行参数。 |
安全建议¶
- 不要把 API 密钥写进浏览器前端代码或随应用一起分发。
- 不要在日志中输出完整密钥。
- 密钥泄露后应立即在账号资料中停用,并生成新密钥。
- 只向
https://ghostclickai.com/api或你明确配置的官方服务地址发送密钥。