FastDDNS 用戶端 API

概述

FastDDNS 用戶端 API 允許任何支援 HTTP 的裝置——router、IP 攝影機、腳本或專用更新軟體——讓你的 DNS hostname 指向目前的 IP 位址。 API 採用簡單的 GET 請求設計：用戶端傳送憑證和 hostname，伺服器會以簡短的狀態碼回應結果。

伺服器 會自動偵測用戶端的公共 IP 位址。指定 IP 不需要額外參數。

認證

API 支援兩種驗證方法。兩者同樣適用——請選擇在你的裝置或 router 上較容易設定的方法。

方法一 — HTTP 基本認證（URL 嵌入）

憑證會以標準的 user:password@host 格式嵌入網址中。這在 router、CCTV 和 HTTP 用戶端函式庫中廣泛受到支援。請使用儀表板上的更新器客戶端金鑰作為密碼。

方法二 — 查詢字串參數

憑證會以純查詢參數的形式傳遞，並與 hostname 一同傳遞。這對於無法設定 HTTP Basic Auth 標頭，但允許使用完整自訂 URL 字串的裝置和 firmware 非常有用。

使用查詢字串驗證的範例：

執行更新

發送一個 GET 請求，更新你帳號註冊的 hostname 的 IP 位址。每次請求更新 會更新一個主機名稱.

端點

URL 格式 — 方法一：HTTP 基本認證

URL 格式 — 方法二：查詢字串

查詢參數

請求範例

方法一 — 透過 HTTPS 使用 HTTP Basic Auth：

方法二 — 透過 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

程式碼範例

殼層 / 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

Python

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 或 proxy，伺服器看到的會是 VPN／proxy 的出口 IP。 使用 getip endpoint 來確認伺服器從你的裝置看到的是哪個 IP。

我收到 911

這表示伺服器端發生暫時性問題。請至少等待 5 分鐘後再重試。請勿快速重複發送請求——這可能會觸發速率限制。請查看 FastDDNS 狀態頁面，確認是否有任何進行中的事件。

我應該多久輪詢一次更新端點？

我們建議每隔 5 分鐘檢查一次 IP 是否變更。當你的 IP 沒有變更時，伺服器會回傳 nochg，這是輕量的 no-op。不建議每分鐘輪詢超過一次，否則可能導致速率限制。