3.4 KiB
KoKonna API research / 接口调查
Rechecked 2026-10-16 against https://kokonna.art/pages/openapi. 错误分类、重试和未知写入处理见 KoKonna 恢复策略。 Base: https://api.kokonna.art/openapi. No fallback to legacy galaxyguide.cn.
| Official endpoint | Frame Flow capability |
|---|---|
| POST /device | Device panel, standardized device model, charging, firmware, sync, cover, storage, native slideshow mode/interval |
| POST /upload | Rendered JPEG upload and immediate activation, asynchronous operation |
| POST /listImages | On-demand cloud metadata gallery, current marker, name/date/geometry/size |
| POST /deleteImage | Confirmed deletion with restore-reference protection |
| GET /image/:apikey/:imageId | Authenticated server proxy, original bytes, lazy cached thumbnails; key never sent to browser |
| POST /displayImageById | Switch through unified DisplayService |
| POST /displayImageByName | Explicit filename switch; ambiguous names rejected |
Native slideshow / 原生轮播
switchType (queue/random) and switchMinute are readable through device.
There is no documented playlist-membership API and no slideshow-setting API.
listImages returns the entire cloud gallery sorted by descending ID; it does
not establish playlist membership. No official pagination parameter is documented.
Frame Flow labels membership as unavailable, native editing unsupported, and
provides its own SQLite-backed playlists as an independent capability.
Cloud constraints / 云端边界
Official limit: 20 requests per minute per device key; local transport reserves headroom at 18. Device state has a 60-second cache, gallery is loaded on demand. Uploads automatically activate a new image; there is no upload-without-activation flag. Gallery-only uploads are therefore local staging, not a fictitious cloud operation. Maximum upstream request size is 50 MB; this service accepts 20 MiB image files with bounded decoded pixels. Only proven-unsent connections or explicit rate-limit rejections may retry a write, within a three-attempt budget. Ambiguous writes are never replayed. Cloud acknowledgement is not physical refresh confirmation; /device synced and imageId drive the operation state. Unconfirmed or interrupted writes become UNKNOWN and block later device writes until read-only reconciliation/explicit acknowledgement.
Reuse / 复用
ClawHub API: https://clawhub.ai/api/v1/skills/kokonna-frame Versioned ZIP: https://clawhub.ai/api/v1/download?slug=kokonna-frame&version=1.2.0 Community package owner: guooscar; metadata license MIT-0. Reused protocol payload and device request, with an injected safe transport. It is a skill/CLI, not a proven NAS daemon, and its default host and screen field assumptions are dated. We implement scheduling, storage, driver normalization, renderer, REST, auth, operations, idempotency, recovery, bilingual UI and deployment independently.
Other inspected repositories:
- https://github.com/patrickchen914/kokonna : Home Assistant integration, MIT; depends on Home Assistant and had legacy host/key-in-image-URL behavior.
- https://github.com/nixihz/kokonna-skill : broader CLI/Hermes endpoint coverage, README MIT, legacy host and raw upstream error messages. Not incorporated.
- https://github.com/zhengweiran66-eng/kokonna-product.html : product page.
No real device key was used during development. Cloud host root returned 530 in an unauthenticated research request; no claim of current real-device connectivity.