DEVELOPER API

API 說明

提供 Codex 與 Claude Skill 使用的 JSON API。所有資料由 PHP 透過檔案鎖寫入單一 /json 目錄，不使用資料庫。

正式 API Base URL：https://4k.1-0.tw/api/

查看 API 首頁GET /api/查看桌布目錄GET api/catalog.php查看統計 APIGET api/stats.php查看偏好 APIGET api/preferences.php查看自動化 APIGET api/automation.php

01 / STATS

統計 API

讀取或更新讚、倒讚、瀏覽與下載數。

GET /api/stats.php

POST /api/stats.php
{
  "client_id": "device-abc123",
  "id": "2",
  "action": "like"
}

支援的 action：like、dislike、view、download。

02 / PREFERENCES

收藏與輪播清單 API

GET /api/preferences.php?client_id=device-abc123

POST /api/preferences.php
{
  "client_id": "device-abc123",
  "action": "playlist_add",
  "id": "3"
}
favorite_toggle收藏或取消收藏
playlist_add加入輪播清單
playlist_remove移除桌布
playlist_save儲存完整排序
schedule_set設定 never／weekly／daily
current_set回寫目前桌布

03 / AUTOMATION

AI 自動化 API

GET /api/automation.php
  ?client_id=device-abc123
  &intent=resolve_schedule
  &date=2026-07-18T06:00:00+08:00

decision=change 時，AI 才能下載並套用回傳的桌布；decision=keep 是正常結果，不應重試。

resolve_schedule立即取得目前桌布的下一張；無資料時隨機選擇
find依 game／dragon／anime／black 搜尋
change_now立即取得指定或推薦桌布

04 / RULES

三個字即時換桌布

  • 只要對已安裝的 AI 說「換桌布」。
  • AI 讀取目前桌布 ID 後呼叫 automation/change_now。
  • 目前桌布存在於清單時，取得清單的下一張。
  • 沒有目前資料時，API 回傳隨機桌布。
  • 成功套用 Windows 桌布後，AI 以 current_set 回寫 ID。

05 / ERRORS

錯誤與安全處理

  • API 失敗最多重試三次，使用 10、30、60 秒間隔。
  • 圖片下載或驗證失敗時保留目前桌布。
  • 只有成功套用後才呼叫 current_set。
  • 正式上線應加入登入權杖、CSRF、頻率限制與允許網域檢查。
閱讀完整技術文件