概述
FastDDNS 客户端 API 允许任何支持 HTTP 的设备——路由器、IP 摄像头、脚本或专用更新软件——保持你的 DNS 主机名指向你当前的 IP 地址。 该 API 遵循简单的 GET 请求设计：客户端发送凭证和主机名，服务器会以简短的状态码响应结果。
服务器会自动检测到客户端的公共IP地址。指定IP不需要额外参数。
认证
该API支持两种认证方式。两者都被同等接受——选择在你的设备或路由器上更容易配置的那个。
user_name和user_pass。这些凭证可以只有
更新该特定主机名后，无法登录FastDDNS管理仪表盘。这种设计限制了设备凭证被泄露时的影响。
方法1 — HTTP基本认证（URL嵌入）
凭据通过标准的user:password@host格式嵌入URL中。路由器、摄像头和HTTP客户端库都广泛支持该功能。用仪表盘上的更新器客户端密钥作为密码。
| 场地 | 描述 | 在哪里可以找到 |
|---|---|---|
| {user_name} | 用户名是在创建时分配给该特定主机名的。 | FastDDNS 仪表盘→主机名→详细信息 |
| {user_pass} | 密码是在创建时分配给该特定主机名的。 | FastDDNS 仪表盘→主机名→详细信息 |
| {hostname} | 更新的完全限定主机名，例如：testhost.fastddns.org。 |
FastDDNS 仪表盘→主机名→详细信息 |
方法2 — 查询字符串参数
凭据作为纯查询参数与hostname一起传递。这对于无法配置 HTTP Basic 认证头部但允许完全自定义 URL 字符串的设备和固件非常有用。
| 参数 | 类型 | 描述 |
|---|---|---|
| {user_name} |
string | 用户名是创建时分配给该主机名的。 |
| {user_pass} | string | 这个主机名在创建时分配的密码。 |
| {hostname} | string | 要更新的完全限定主机名，例如 testhost.fastddns.org。 |
使用查询字符串认证的示例：
执行更新
发送一个GET请求，更新注册在你账户中的主机名的IP地址。每次请求会更新一个主机名。
终点
https 替换为 http。URL 格式 — 方法1：HTTP 基本认证
URL 格式 — 方法二：查询字符串
查询参数
| 参数 | 类型 | 描述 |
|---|---|---|
| hostname 要求 | string | 更新的主机名（FQDN），例如 myhome.fastddns.net 或 testhost.fastddns.org。每个请求只支持一个主机名。 |
| user_name 方法二 | string | 这个主机名的用户名。使用查询字符串认证（方法2）时必须这样做。使用HTTP Basic Auth（方法1）时不需要。 |
| user_pass 方法二 | string | 这个主机名的密码。使用查询字符串认证（方法2）时必须这样做。使用HTTP Basic Auth（方法1）时不需要。 |
myip参数。
示例请求
方法1 — 基于HTTPS的HTTP基本认证：
方法二 — HTTPS上的查询字符串：
使用纯HTTP（仅测试/可信网络）：
退货代码
所有更新响应都会返回HTTP状态200 OK 正文是纯文本。 你的客户必须解析这段文本，以确定更新的实际结果。
更新成功
主机名记录已更新为检测到的IP地址。实际的IP会包含在回复中，例如good 203.0.113.45。这是IP变更时的预期反应。
无需更改
主机名已经指向检测到的IP地址——不需要更新。当前IP包含在内，例如nochg 203.0.113.45。这是正常的、无错误的响应。
认证失败
用户名或更新客户端密钥错误或已被撤销。请在FastDDNS仪表盘中验证你的凭证。不要自动重试——先修复凭证。
主机名未找到
指定的主机名不存在于你的账户中，或者不符合动态更新的资格。检查主机名拼写，确认它是否注册在你的账户下。
服务器错误
FastDDNS 服务器端发生了内部错误。至少等5分钟再重试。如果问题依旧，请查看FastDDNS状态页面或联系支持。
回应摘要
| 回应文本 | HTTP 状态 | 含义 | 需要采取行动 |
|---|---|---|---|
| good {ip} | 200 | IP 更新成功 | 无 — 更新完成 |
| nochg {ip} | 200 | IP未变，未更新 | 没有——已经是新的 |
| badauth | 200 | 无效凭证 | 检查用户名/客户端密钥 |
| nohost | 200 | 主机名未注册 | 在仪表盘中验证主机名 |
| 911 | 200 | 服务器端错误 | 5+分钟后重试 |
200——文本正文告诉你更新是否真的成功。
获取客户端IP
FastDDNS 提供了一个简单的工具端点，返回服务器所见的公共 IP 地址。 这对调试、验证设备发送的IP或在调用更新端点前的自定义脚本中非常有用。
终点
反响
返回HTTP200 OK 在响应正文中，检测到的公共IP地址以明文形式显示。
# Example response body
203.0.113.45RESPONSE示例请求
使用 curl：
curl https://client.fastddns.net/dyndns/getipSHELL代码示例
Shell / cURL
# Method 1: HTTP Basic Auth (HTTPS, IP auto-detected)
curl "https://fastddnstest:[email protected]/?hostname=testhost.fastddns.org"
# Method 2: Query string credentials
curl "https://client.fastddns.net/?hostname=testhost.fastddns.org&user_name=fastddnstest&user_pass=569832"
# Check what IP the server sees from your device
curl "https://client.fastddns.net/dyndns/getip"SHELL蟒蛇
import requests
HOSTNAME = "testhost.fastddns.org"
USER_NAME = "fastddnstest"
USER_PASS = "569832"
# Method 1: HTTP Basic Auth
resp = requests.get(
"https://client.fastddns.net/",
auth=(USER_NAME, USER_PASS),
params={"hostname": HOSTNAME}
)
# Method 2: Query string
# resp = requests.get("https://client.fastddns.net/", params={
# "hostname": HOSTNAME, "user_name": USER_NAME, "user_pass": USER_PASS
# })
body = resp.text.strip()
if body.startswith("good"):
print(f"Updated successfully: {body}")
elif body.startswith("nochg"):
print(f"No change needed: {body}")
elif body == "badauth":
print("Authentication failed. Check credentials.")
elif body == "nohost":
print("Hostname not found.")
elif body == "911":
print("Server error. Try again later.")PYTHONPHP
<?php
$hostname = 'testhost.fastddns.org';
$user_name = 'fastddnstest';
$user_pass = '569832';
// Method 1: HTTP Basic Auth embedded in URL
$url = "https://{$user_name}:{$user_pass}@client.fastddns.net/?hostname=" . urlencode($hostname);
// Method 2: Query string credentials
// $url = "https://client.fastddns.net/?hostname=" . urlencode($hostname)
// . "&user_name=" . urlencode($user_name)
// . "&user_pass=" . urlencode($user_pass);
$ctx = stream_context_create(['http' => ['timeout' => 10]]);
$body = trim(file_get_contents($url, false, $ctx));
switch (true) {
case str_starts_with($body, 'good'):
echo "Updated: {$body}\n"; break;
case str_starts_with($body, 'nochg'):
echo "No change: {$body}\n"; break;
case $body === 'badauth':
echo "Auth failed. Check hostname credentials.\n"; break;
case $body === 'nohost':
echo "Hostname not found.\n"; break;
case $body === '911':
echo "Server error, retry later.\n"; break;
}PHPBash（Cron / 路由器脚本）
#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="fastddnstest"
USER_PASS="569832"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s "https://${USER_NAME}:${USER_PASS}@client.fastddns.net/?hostname=${HOSTNAME}")
# Method 2: Query string (uncomment to use instead)
# RESULT=$(curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}")
case "$RESULT" in
good*) echo "[OK] $RESULT" ;;
nochg*) echo "[OK] $RESULT" ;;
badauth) echo "[ERR] Bad credentials — check hostname user/pass"; exit 1 ;;
nohost) echo "[ERR] Hostname not found"; exit 1 ;;
911) echo "[ERR] Server error, retry later"; exit 1 ;;
*) echo "[WARN] Unknown response: $RESULT" ;;
esacBASH故障排除
我收到badauth
所提供的user_name或user_pass与分配给该主机名的凭证不匹配。
每个主机名都有独立的凭据——可以在你的仪表盘下找到主机名→详情
.
请注意，这些凭据是针对主机名的，不能用于登录FastDDNS管理门户。
如果你最近重置了凭证，请更新使用该主机名的所有设备。
我收到nohost
hostname参数中的主机名不存在，或者不属于所提供的凭证所识别的账户。
检查主机名是否有错别字，确认它在你的仪表盘上列出，并确认user_name和user_pass是否匹配那个特定的主机名
.
服务器检测到错误的 IP
服务器使用TCP连接的源IP。如果你的设备位于NAT路由器后面，路由器的公共IP会被检测到——这通常是理想的行为。如果你在VPN或代理上，服务器会看到VPN/代理的退出IP。 用getip endpoint来验证服务器从你的设备看到的IP地址。
我收到911
这表明存在临时的服务器端问题。至少等5分钟再重试。不要快速循环请求——这可能会触发速率限制。请查看FastDDNS状态页面是否有任何活跃事件。
我应该多久轮询一次更新端点？
我们建议每5分钟检查一次IP变更。当你的IP没有变化时，服务器会返回nochg，这是一种轻量级的无操作。不建议每分钟超过一次轮询，可能导致速率限制。