API 接口文档 - 壹号DNS

简介

通过 API 密钥，您可以在第三方程序中管理解析记录，实现自动化域名解析。支持添加、更新、暂停、启用、续费和删除解析记录等操作。

Base URL

https://www.1hdns.cn/api/v1

API 密钥管理

前往控制台 → API密钥创建和管理您的密钥。

功能特性

支持多周期购买（月付、季付、半年付、年付）
自动扣除积分，支持用户组折扣
DNS平台重复前缀检查，避免冲突
支持上游域名对接和本地DNS平台（阿里云、腾讯云、西部数码、火山引擎）
完善的错误处理和速率限制保护

认证方式

所有 API 请求必须通过 Authorization 请求头携带 用户名 和 API密钥 进行认证。

Bearer Token（唯一支持方式）

Authorization: Bearer 用户名:api_key

示例：Authorization: Bearer demo:xh_abc123...

安全提示：请勿将密钥拼接到 URL 中（如 ?api_key=...），URL 参数会被服务器日志记录，存在密钥泄露风险。本接口仅支持 Header 认证。

响应格式

所有接口返回 JSON 格式，结构如下：

{
  "code": 0,       // 0=成功，非0=失败
  "message": "ok",
  "data": ...          // 具体数据
}

常见错误码

HTTP状态码	说明
200	请求成功
400	请求参数错误
401	认证失败（API密钥无效或格式错误）
403	无权访问（账号被禁用或无权操作该资源）
404	资源不存在
429	请求过于频繁（10分钟内认证失败5次）

GET /api/v1/account

获取当前账户信息，包括积分余额和用户组折扣。

响应示例

{
  "code": 0,
  "data": {
    "user_id": 1,
    "username": "demo",
    "point": 500,
    "group_name": "普通用户",
    "discount": 100
  }
}

GET /api/v1/domains

获取当前账户可用的域名后缀列表及多周期价格信息。

响应示例

{
  "code": 0,
  "data": [{
    "id": 1,
    "domain": "example.com",
    "periods": {
      "month": {
        "price": 100,
        "sale_price": 80,
        "renew_price": 90,
        "first_free": 0,
        "first_price": 0
      },
      "quarter": { // 3个月 },
      "half_year": { // 6个月 },
      "year": { // 12个月 }
    }
  }]
}

说明：periods 字段包含该域名支持的所有周期价格。price 为原价，sale_price 为促销价，renew_price 为续费价，first_free 表示首次是否免费，first_price 为首次购买价格。

GET /api/v1/domains/prices

获取所有域名的价格列表（含多周期价格）。

响应示例

{
  "code": 0,
  "data": [{
    "domain": "example.com",
    "periods": {
      "month": {
        "price": 100,
        "sale_price": 80,
        "renew_price": 90,
        "first_free": 0,
        "first_price": 0
      },
      "year": { // 同上结构 }
    }
  }]
}

GET /api/v1/domains/{domain}/records

获取指定域名的所有解析记录。{domain} 为域名后缀，如 example.com。

响应示例

{
  "code": 0,
  "data": {
    "records": [{
      "id": 1,
      "name": "www",
      "type": "A",
      "value": "1.2.3.4",
      "line": "default",
      "ttl": 600,
      "status": "active",
      "expiry_date": "2026-01-01 00:00:00",
      "created_at": "2025-01-01 10:30:00"
    }]
  }
}

GET /api/v1/records

获取当前账户所有解析记录。

响应示例

{
  "code": 0,
  "data": [{
    "id": 1,
    "name": "www",
    "domain": "example.com",
    "full_domain": "www.example.com",
    "type": "A",
    "value": "1.2.3.4",
    "line": "default",
    "ttl": 600,
    "status": "active",
    "expiry_date": "2026-01-01 00:00:00",
    "created_at": "2025-01-01 10:30:00"
  }]
}

GET /api/v1/records/{id}

获取单条解析记录的详细信息。{id} 为解析记录的 ID。

响应示例

{
  "code": 0,
  "data": {
    "id": 1,
    "name": "www",
    "domain": "example.com",
    "full_domain": "www.example.com",
    "type": "A",
    "value": "1.2.3.4",
    "line": "default",
    "ttl": 600,
    "status": "active",
    "expiry_date": "2026-01-01 00:00:00",
    "created_at": "2025-01-01 10:30:00"
  }
}

POST /api/v1/records

添加新的解析记录，会自动扣除积分。

请求参数

参数	类型	必填	说明
name	string	必填	前缀，如 www、blog、@（表示根域名）
domain	string	必填	域名后缀，如 example.com
type	string	必填	记录类型：A（IPv4地址）/ CNAME（别名）/ AAAA（IPv6地址）/ MX（邮件交换）/ TXT（文本记录）
value	string	必填	解析值，根据类型填写对应的值（IP地址、域名等）
period	string	可选	购买周期：month（1个月）/ quarter（3个月）/ half_year（6个月）/ year（1年，默认）
ttl	int	可选	TTL（生存时间），单位秒，默认 600
line	string	可选	解析线路，默认 default（默认线路）

请求示例

{
  "name": "www",
  "domain": "example.com",
  "type": "A",
  "value": "1.2.3.4",
  "period": "month",
  "ttl": 600,
  "line": "default"
}

响应示例

{
  "code": 0,
  "message": "解析记录添加成功",
  "data": {
    "id": 123,
    "name": "www",
    "domain": "example.com",
    "full_domain": "www.example.com",
    "type": "A",
    "value": "1.2.3.4",
    "ttl": 600,
    "status": "active",
    "expiry_date": "2026-05-02 10:30:00",
    "points_cost": 100
  }
}

说明：不同周期对应不同的价格和到期时间。如果域名未设置多周期价格，将使用默认价格。添加成功后会自动扣除相应积分。

POST /api/v1/records/{id}

更新指定解析记录的信息。{id} 为解析记录的 ID。

请求参数

参数	类型	必填	说明
name	string	可选	前缀，如 www、blog
type	string	可选	记录类型：A / CNAME / AAAA / MX / TXT
value	string	可选	解析值，根据类型填写对应的值
line	string	可选	解析线路
ttl	int	可选	TTL（生存时间），单位秒

请求示例

{
  "name": "blog",
  "value": "5.6.7.8",
  "ttl": 300
}

响应示例

{
  "code": 0,
  "message": "解析记录更新成功",
  "data": []
}

注意：如果修改前缀(name)，系统会检查新前缀是否在DNS平台已存在，避免重复添加。

POST /api/v1/records/{id}/suspend

暂停指定解析记录。{id} 为解析记录的 ID。

响应示例

{
  "code": 0,
  "message": "解析已暂停",
  "data": []
}

POST /api/v1/records/{id}/resume

启用已暂停的解析记录。{id} 为解析记录的 ID。

响应示例

{
  "code": 0,
  "message": "解析已启用",
  "data": []
}

POST /api/v1/records/{id}/renew

续费指定解析记录。{id} 为解析记录的 ID。

请求参数

参数	类型	必填	说明
period	string	可选	续费周期：month / quarter / half_year / year（默认）
months	int	可选	续费月数（1-120），如果指定 period 则忽略此参数

请求示例

{
  "period": "quarter"
}

响应示例

{
  "code": 0,
  "message": "续费成功",
  "data": {
    "id": 123,
    "expiry_date": "2026-08-02 10:30:00",
    "months": 3,
    "points_cost": 250
  }
}

说明：续费会自动扣除相应积分，如果记录处于暂停状态，续费后会自动恢复为启用状态。

DELETE /api/v1/records/{id}

删除指定解析记录，同时从 DNS 平台删除。{id} 为解析记录的 ID。

响应示例

{
  "code": 0,
  "message": "解析记录已删除",
  "data": []
}

警告：删除操作不可恢复，请谨慎操作。