DEVELOPER DOCS

用代码调用快连，把加速嵌入业务

快连提供 RESTful API 与多语言 SDK，支持节点查询、下载任务创建、用量统计、缓存刷新等操作。企业版客户可获得完整 API 权限与专属技术支持。

5 分钟快速接入下载 SDK

API OVERVIEW

接口总览

所有接口统一以 https://api.kuilanc.com.cn/v1 为前缀，返回 JSON 格式数据。

认证

使用 API Key + HMAC-SHA256 签名，支持 IP 白名单与权限粒度控制。

节点

查询全球加速节点列表、实时健康度与推荐接入点。

任务

创建下载任务、获取任务状态、暂停/恢复/取消任务。

统计

查询流量、带宽、请求数、错误率等用量数据。

缓存

按 URL 或目录刷新缓存，预热指定资源到边缘节点。

Webhook

订阅任务完成、节点告警、账单阈值等事件通知。

QUICK START

四步接入 API

按照下面步骤，最快 5 分钟即可发起第一个加速下载任务。

1
注册并获取 API Key登录控制台，进入"开发者中心 - API 密钥"，创建 Access Key 与 Secret Key。务必妥善保存 Secret Key，它只显示一次。
2
安装 SDK 或准备签名逻辑我们提供 Python、Node.js、Go、Java、PHP 的 SDK。若直接调用 REST API，请参考鉴权章节实现 HMAC-SHA256 签名。
3
查询推荐节点调用 GET /v1/nodes/recommended 获取离你最近的可用节点，为后续任务创建做准备。
4
创建下载任务调用 POST /v1/tasks 传入目标 URL 与节点选择策略，返回 task_id 后即可轮询任务状态或等待 Webhook 通知。

AUTHENTICATION

认证方式

每个请求都需要在 HTTP Header 中携带签名，防止密钥泄露。

请求头格式

Authorization: KL <AccessKey>:<Signature>
X-KL-Timestamp: 1680000000
X-KL-Nonce: a1b2c3d4e5f6

Signature 由 HTTP Method、请求路径、时间戳、Nonce 与请求体拼接后，用 Secret Key 做 HMAC-SHA256 生成。

Python 签名示例

import hmac, hashlib, base64

def sign(secret, method, path, ts, nonce, body=''):
    msg = f"{method}\n{path}\n{ts}\n{nonce}\n{body}"
    return base64.b64encode(
        hmac.new(secret.encode(), msg.encode(), hashlib.sha256).digest()
    ).decode()

ENDPOINTS

常用接口示例

GET/v1/nodes/recommended

获取推荐接入节点。支持按国家、运营商、延迟上限过滤。

// 响应示例
{
  "nodes": [
    {
      "id": "node-bj-01",
      "region": "CN-Beijing",
      "isp": "BGP",
      "latency_ms": 12,
      "load": 0.34
    }
  ]
}

POST/v1/tasks

创建下载加速任务。支持指定线程数、分块大小、保存路径与回调地址。

// 请求示例
{
  "url": "https://example.com/file.zip",
  "node_id": "node-bj-01",
  "threads": 16,
  "callback": "https://your-domain.com/webhook"
}

// 响应示例
{
  "task_id": "task_20260716_abc123",
  "status": "pending",
  "created_at": "2026-07-16T08:30:00Z"
}

GET/v1/tasks/{task_id}

查询任务状态与实时进度。

{
  "task_id": "task_20260716_abc123",
  "status": "downloading",
  "progress": 0.68,
  "speed_bps": 125000000,
  "downloaded_bytes": 734003200,
  "total_bytes": 1073741824
}

POST/v1/cache/purge

按 URL 刷新缓存，支持单条与批量。

{
  "urls": [
    "https://cdn.kuilanc.com.cn/static/app.css",
    "https://cdn.kuilanc.com.cn/static/app.js"
  ]
}

ERROR CODES

错误码说明

错误码	HTTP 状态	含义	处理建议
2000	400	请求参数错误	检查字段类型与必填项
2001	401	签名无效或已过期	重新生成签名，校准时钟
2002	403	权限不足	确认 API Key 权限范围
2003	404	资源不存在	检查 task_id 或 node_id
2004	429	请求过于频繁	降低请求频率或申请提高配额
5000	500	服务器内部错误	稍后重试或联系技术支持

SDK

多语言 SDK

官方维护的 SDK 已经处理好了签名、重试与错误解析。

Python

pip install kuilanc-sdk

Node.js

npm install @kuilanc/sdk

Go

go get github.com/kuilanc/go-sdk

Java

Maven / Gradle 仓库均已发布

PHP

composer require kuilanc/sdk

CLI

跨平台命令行工具，支持批量任务