跳转至

gcbps API 调用

GC-VIP 用户可以通过外部 API 运行自己云盘内或已经购买的 gcbps。API 密钥只会在生成时完整显示一次,请像保存密码一样妥善保存,不要写入公开仓库、聊天记录或客户端安装包。

准备工作

  1. 在账号资料中生成 API 密钥。密钥以 gcak_ 开头。
  2. 确认账号的 GC-VIP 处于有效状态。
  3. 准备要运行的 gcbpsId。你可以先列出可运行来源,也可以使用已经保存的 ID。
  4. 如果自动化包含公开输入变量,先读取变量清单,再按照变量名称和类型提交数据。

请求时可以使用以下任一认证请求头:

Authorization: Bearer gcak_...
X-API-Key: gcak_...

接口一览

用途 方法和路径
列出可运行来源 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

调用流程

  1. 调用 sources 获取当前密钥可以运行的来源,或者直接使用已知的 gcbpsId
  2. 调用 manifest 读取公开变量名、变量类型和输入要求。
  3. 如果变量需要图片、视频或文件,先上传到 input-files 并保存返回的 inputId
  4. 调用 runs 创建任务。任务会消耗当前账号的 token 和 G币。
  5. 使用返回的 jobId 轮询任务状态。如果本地丢失了 jobId,可以通过任务列表查询最近任务。
  6. 任务完成后,使用任务结果中的输出信息下载文件。

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 或你明确配置的官方服务地址发送密钥。