API 文档

本地安装 SDK（alpha — 暂不发布到 PyPI / npm）。

# Training pool API is the customer-facing primary flow.
# Use the raw HTTP examples above; SDK training helpers land in Stage 18+.
# See docs/customer-custom-training-guide.md for the full
# dataset → training_package → training_job flow.

// Training pool API is the customer-facing primary flow.
// Use the raw HTTP examples above; SDK training helpers land in Stage 18+.
// See docs/customer-custom-training-guide.md for the full
// dataset → training_package → training_job flow.

所有程序化调用需要在 X-API-Key 头中携带 API Key。请到 API Key 页面创建。

X-API-Key: sk_alpha_REPLACE_ME_WITH_YOUR_KEY

GPU-Agent 是面向客户自定义训练的家庭异构算力网络。客户上传自己的数据集和训练包（Python 入口 zip），平台将训练任务规划成 CPU + GPU 计算单元 DAG，分发给具备能力的受控级家庭节点执行。请使用左侧的「数据集 / 训练包 / 训练任务」页面，并参考 customer-custom-training-guide 文档。

# 1) create the training job (uses an already-finalized dataset + package)
curl -fsS -X POST 'https://api-staging.c3pool.cn/api/v1/customer/training-jobs' \
  -H 'X-API-Key: sk_alpha_REPLACE_ME_WITH_YOUR_KEY' \
  -H 'Idempotency-Key: client-uuid-12345678' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "tiny-mlp-fine-tune",
    "dataset_id": "<your-dataset-uuid>",
    "training_package_id": "<your-package-uuid>",
    "required_vram_mb": 8000,
    "required_disk_mb": 1024,
    "max_runtime_seconds": 600,
    "sensitivity": "low_sensitive"
  }'

# 2) poll status (every 5s; jobs typically complete in minutes)
curl -fsS 'https://api-staging.c3pool.cn/api/v1/customer/training-jobs/<job-id>' \
  -H 'X-API-Key: sk_alpha_REPLACE_ME_WITH_YOUR_KEY' | jq '.status'

# 3) download an artifact (signed URL minted on demand, 900s TTL)
curl -fsS -X POST 'https://api-staging.c3pool.cn/api/v1/customer/training-jobs/<job-id>/artifacts/<artifact-id>/download-url' \
  -H 'X-API-Key: sk_alpha_REPLACE_ME_WITH_YOUR_KEY' | jq -r '.download_url'

const r = await fetch('https://api-staging.c3pool.cn/api/v1/customer/training-jobs', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_alpha_REPLACE_ME_WITH_YOUR_KEY',
    'Idempotency-Key': 'client-uuid-12345678',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'tiny-mlp-fine-tune',
    dataset_id: '<your-dataset-uuid>',
    training_package_id: '<your-package-uuid>',
    required_vram_mb: 8000,
    required_disk_mb: 1024,
    max_runtime_seconds: 600,
    sensitivity: 'low_sensitive',
  }),
});
const job = await r.json();
console.log(job.id);

import os, requests
r = requests.post(
    "https://api-staging.c3pool.cn/api/v1/customer/training-jobs",
    headers={
        "X-API-Key": os.environ["GPU_AGENT_API_KEY"],
        "Idempotency-Key": "client-uuid-12345678",
    },
    json={
        "name": "tiny-mlp-fine-tune",
        "dataset_id": "<your-dataset-uuid>",
        "training_package_id": "<your-package-uuid>",
        "required_vram_mb": 8000,
        "required_disk_mb": 1024,
        "max_runtime_seconds": 600,
        "sensitivity": "low_sensitive",
    },
    timeout=15,
)
r.raise_for_status()
print(r.json()["id"])

在 POST /customer/training-jobs 上传 Idempotency-Key 头可让重试安全。相同 key + 相同请求体返回原任务；相同 key + 不同请求体会被 IDEMPOTENCY_CONFLICT 拒绝。

Idempotency-Key: client-uuid-12345678

列表接口返回 { data, page: { limit, next_cursor, has_more } }。仅支持向前游标。默认 limit 50，最大 100。

{
  "data": [ ... ],
  "page": { "limit": 50, "next_cursor": "eyJ0cy...", "has_more": true }
}

• 每个客户每分钟最多 10 个训练任务。
• 同时运行的训练任务最多 3 个。
• 每个客户每天最多 200 个 compute unit。
• 所有 customer 响应都带 X-RateLimit-Limit / -Remaining / -Reset；429 响应带 Retry-After。

• 每个完成的 compute unit 按工作负载费率扣积分。
• 失败 / 被拒 / 校验未通过的 compute unit **不**扣积分。
• 重放的重复完成事件按 compute_unit_id 去重,不会重复扣费。