开放 API 文档

快速开始 3 步接入

1. 创建 API Key

在客户端进入「开放 API」页面，点击「生成密钥」。密钥形如 dk_live_xxxxxxxx...，仅在生成时完整显示一次，请妥善保存。

2. 发起第一个请求

复制curl -X GET "http://103.112.185.167:8899/open/v1/ping" \
  -H "X-API-Key: dk_live_你的密钥"

复制const res = await fetch('http://103.112.185.167:8899/open/v1/ping', {
  headers: { 'X-API-Key': 'dk_live_你的密钥' }
});
const data = await res.json();
console.log(data); // { code: 0, msg: 'pong', data: { api_version: 'v1', ... } }

复制import requests

res = requests.get(
    'http://103.112.185.167:8899/open/v1/ping',
    headers={'X-API-Key': 'dk_live_你的密钥'},
    timeout=10,
)
print(res.json())

3. 创建浏览器配置

复制curl -X POST "http://103.112.185.167:8899/open/v1/profiles" \
  -H "X-API-Key: dk_live_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "亚马逊店铺-01",
    "group_id": 1,
    "os_type": "windows",
    "remark": "美国站"
  }'

鉴权与错误码

支持以下三种传入方式，优先级从高到低：

统一响应结构

复制{
  "code": 0,                 // 0 = 成功；非 0 = 失败（与 HTTP 状态码一致）
  "msg": "ok",
  "data": { ... },           // 业务数据，失败时可能为 null
  "request_id": "a1b2c3d4e5f6a7b8"   // 排查问题时提供此 ID
}

错误码

基础接口

复制{
  "code": 0,
  "msg": "pong",
  "data": {
    "server_time": "2026-11-06T12:00:00+08:00",
    "api_version": "v1",
    "user_id": 1,
    "rate_limit": 120
  }
}

复制{
  "code": 0,
  "msg": "ok",
  "data": {
    "profiles": 12,
    "groups": 3,
    "proxies": 5,
    "running_profiles": 2
  }
}

分组管理

复制{
  "code": 0,
  "data": {
    "list": [
      { "id": 1, "name": "默认分组", "profile_count": 8 },
      { "id": 2, "name": "美国站", "profile_count": 4 }
    ],
    "total": 2
  }
}

复制curl -X POST "http://103.112.185.167:8899/open/v1/groups" \
  -H "X-API-Key: dk_live_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"name":"美国站"}'

浏览器配置

复制curl "http://103.112.185.167:8899/open/v1/profiles?page=1&limit=20&group_id=1" \
  -H "X-API-Key: dk_live_你的密钥"

复制curl -X POST "http://103.112.185.167:8899/open/v1/profiles" \
  -H "X-API-Key: dk_live_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "安卓-01",
    "group_id": 1,
    "os_type": "android",
    "browser_config": {
      "deviceMode": "android",
      "phoneBrand": "Samsung",
      "deviceModel": "Galaxy S24",
      "mobileOsVersion": "14",
      "screenResolution": "412x915",
      "timezoneMode": "ip"
    }
  }'

代理列表

复制{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "type": "socks5",
        "ip": "1.2.3.4",
        "port": 1080,
        "username": "user",
        "region": "US",
        "status": "active"
      }
    ],
    "total": 1
  }
}

指纹参数

调用 GET /open/v1/fingerprint/options 可获取当前版本支持的完整字段说明与默认值，建议接入时以接口返回为准，避免硬编码。

复制curl "http://103.112.185.167:8899/open/v1/fingerprint/options" \
  -H "X-API-Key: dk_live_你的密钥"

常用字段

接入示例

批量创建配置（Node.js）

复制const BASE = 'http://103.112.185.167:8899/open/v1';
const KEY  = 'dk_live_你的密钥';

async function createProfile(name, groupId) {
  const res = await fetch(`${BASE}/profiles`, {
    method: 'POST',
    headers: {
      'X-API-Key': KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name, group_id: groupId, os_type: 'windows' }),
  });
  const json = await res.json();
  if (json.code !== 0) throw new Error(`${res.status}: ${json.msg}`);
  return json.data;
}

(async () => {
  for (let i = 1; i <= 10; i++) {
    const p = await createProfile(`店铺-${String(i).padStart(2, '0')}`, 1);
    console.log('created', p.id);
  }
})();

错误处理建议

复制async function api(path, options = {}) {
  const res = await fetch(BASE + path, {
    ...options,
    headers: { 'X-API-Key': KEY, 'Content-Type': 'application/json', ...(options.headers || {}) },
  });

  if (res.status === 429) {
    const retryAfter = Number(res.headers.get('Retry-After') || 60);
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return api(path, options); // 重试一次
  }

  const json = await res.json();
  if (json.code !== 0) {
    // 记录 request_id 方便排查
    console.error(json.request_id, res.status, json.msg);
    throw new Error(json.msg);
  }
  return json.data;
}