57 lines
3.4 KiB
Markdown
57 lines
3.4 KiB
Markdown
# KoKonna API research / 接口调查
|
|
|
|
Rechecked 2026-10-16 against https://kokonna.art/pages/openapi.
|
|
错误分类、重试和未知写入处理见 [KoKonna 恢复策略](KOKONNA_RECOVERY.md)。
|
|
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.
|