FastDDNS 客户端 API

概述

FastDDNS 客户端 API 允许任何支持 HTTP 的设备——router、IP 摄像头、脚本或专用更新软件——让你的 DNS hostname 始终指向当前 IP 地址。 该 API 采用简单的 GET 请求设计：客户端发送凭据和 hostname，服务器返回简短的状态码，表示操作结果。

服务器 公共IP地址。指定IP不需要额外参数。

认证

该 API 支持两种认证方式。两种方式的接受程度相同——请选择在你的设备或 router 上更易配置的一种。

方法 1 — HTTP Basic Auth（嵌入 URL）

凭据通过标准的user:password@host格式。路由器、摄像头和HTTP客户端库都广泛支持该功能。使用仪表盘上的更新器客户端密钥作为密码。

方法2 — 查询字符串参数

凭据作为纯查询参数与hostname一起传递。这对于无法配置 HTTP Basic 认证头部但允许完全自定义 URL 字符串的设备和固件非常有用。

使用查询字符串认证的示例：

执行更新

发送单个 GET 请求，更新注册到你账户中的 hostname 的 IP 地址。每次请求只更新一个主机名。

端点

URL 格式 — 方法 1：HTTP 基本认证

URL 格式 — 方法二：查询字符串

查询参数

示例请求

方法 1 — 通过 HTTPS 使用 HTTP 基本认证：

方法二 — HTTPS 上的查询字符串：

使用纯 HTTP（仅用于测试或受信任的网络）：

返回代码

所有更新响应都会返回 HTTP 状态 200 OK，正文为纯文本。 客户端必须解析此文本，以确定更新的实际结果。

响应摘要

获取客户端 IP

FastDDNS 提供了一个简单的工具端点，可返回服务器检测到的公共 IP 地址。 这对于调试、确认设备发送请求时使用的 IP，或在调用更新端点前用于自定义脚本都很有帮助。

端点

响应

返回 HTTP 200 OK，响应正文中以纯文本形式返回检测到的公共 IP 地址。

# Example response body
203.0.113.45RESPONSE

示例请求

使用 curl：

curl https://client.fastddns.net/dyndns/getipSHELL

代码示例

Shell / cURL

# Recommended: let curl build the Authorization header (-u), so the
# credentials never appear in the URL.
HOSTNAME="myhome.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
curl -s -u "${USER_NAME}:${USER_PASS}" "https://client.fastddns.net/?hostname=${HOSTNAME}"
# Legacy form, for devices that can only be given one URL field:
curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}"
# Check what IP the server sees from your device
curl -s "https://client.fastddns.net/dyndns/getip"SHELL

蟒蛇

import requests
HOSTNAME  = "testhost.fastddns.org"
USER_NAME = "YOUR_UPDATE_USERNAME"
USER_PASS = "YOUR_UPDATE_PASSWORD"
# 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.")PYTHON

PHP

<?php
$hostname  = 'testhost.fastddns.org';
$user_name = 'YOUR_UPDATE_USERNAME';
$user_pass = 'YOUR_UPDATE_PASSWORD';
// Recommended: Basic Auth in a request header, so the password is not
// part of the URL and cannot leak through logs or error messages.
$url = "https://client.fastddns.net/?hostname=" . urlencode($hostname);
$auth = 'Basic ' . base64_encode($user_name . ':' . $user_pass);
// 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,
    'header'  => "Authorization: {$auth}\r\n",
]]);
$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;
}PHP

Bash（Cron / router 脚本）

#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s -u "${USER_NAME}:${USER_PASS}" "https://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与分配给该主机名的凭证不匹配。 每个主机名都有独立的凭据——可以在你的仪表盘下找到主机名→详情. 请注意，这些凭据专属于该 hostname，不能用于登录 FastDDNS 管理门户。 如果你最近重置了凭证，请更新所有使用该 hostname 的设备。

我收到 nohost

hostname 提供的参数中的 hostname 不存在，或者不属于所提供的凭证所识别的账户。 检查 hostname 是否有错别字，确认它已列在你的仪表盘中，并确认user_name和user_pass提供的凭证是否匹配那个特定的主机名。

服务器检测到错误的 IP

服务器使用TCP 连接的源 IP。如果你的设备位于 NAT router 后面，检测到的将是 router 的公共 IP——这通常正是所需的行为。如果你使用 VPN 或代理，服务器看到的将是 VPN 或代理的出口 IP。 使用getip endpoint来验证服务器从你的设备看到的IP地址。

我收到 911

这表明存在临时的服务器端问题。请至少等待 5 分钟后再重试。不要快速循环发送请求——这可能会触发速率限制。请查看 FastDDNS 状态页面，确认是否有正在处理的事件。

我应该多久轮询一次更新端点？

我们建议每5 分钟。当你的 IP 未发生变化时，服务器会返回nochg，这是一种轻量级的无操作响应。不建议每分钟轮询超过一次，否则可能会触发速率限制。