zinohome Image Generation
Tool budget
| Path | Calls | Steps |
|---|---|---|
| Default | 4 | submit (timeout 90) → poll_until_done (timeout 300) → download → message |
If submit returns image_urls |
3 | submit → download → message |
| Fallback after failed | +2 | models.py → submit.py (new model) |
Hard rule: DO NOT read_file / ls this skill directory. DO NOT run models.py before the first submit.py. All info needed to build JSON is in this file.
Default path
submit.py '<compact_json>'with exec timeout ≥ 90 → returnstask_id+ possiblyimage_urls- Always run
poll_until_done.py <task_id>with exec timeout ≥ 300 unless step 1 already returnedimage_urls download.py '<image_url_or_json_array>' '<name>'— auto saves to workspace outputs- One
message(media)— done
Important: submit may take 30–90s even for "sync" models under load. Always set exec timeout high enough — never use default.
Silent policy
No user-visible status text until the final delivery. Only the final message() with media. Quota message is the single exception (exact string in Error table).
Model name rule: 对用户使用 API 的 display_name：Seedream V5.0 Lite / MiniDesk Pro / MiniDesk 2。
Token & URLs
- Token: auto from
~/.deskclaw/deskclaw-settings.json→auth.token(优先) →authToken(回退), or envNODESTUDIO_TOKEN. - NodeStudio base: env
NODESTUDIO_URL(defaulthttps://nostudio-api.deskclaw.me). - Scripts handle token + URL automatically, agent does not need to read config or pass token.
Models (no pre-flight models.sh)
Default priority（用户未指定模型时）
| Priority | model_id | Display Name | Type | Notes |
|---|---|---|---|---|
| 1 | nano2 |
MiniDesk 2 | may sync | 0.5K–4K, 6 ref, ratios: 1:1 3:2 2:3 3:4 4:3 4:5 5:4 9:16 16:9 21:9 1:4 4:1 1:8 8:1, fastest |
| 2 | nano-pro |
MiniDesk Pro | may sync | 1K–4K, 6 ref, ratios: 1:1 3:2 2:3 3:4 4:3 4:5 5:4 9:16 16:9 21:9, 30-90s |
| 3 | seedream |
Seedream V5.0 Lite | async | 2K/3K, 14 ref, ratios: 21:9 16:9 3:2 4:3 1:1 3:4 2:3 9:16, up to 4 outputs, 60-180s |
Default model: nano2. Fallback: nano-pro → seedream. Call models.py only when retrying after failed or user names a model you must validate.
Quality priority（用户要求"最好/最高质量"时）
| Quality | model_id | Display Name |
|---|---|---|
| 1 | nano-pro |
MiniDesk Pro |
| 2 | nano2 |
MiniDesk 2 |
| 3 | seedream |
Seedream V5.0 Lite |
当用户明确说"用最好的模型""质量最高""高清大图"等质量优先意图时，按此顺序选择。
Build JSON
Compact, no spaces after : or ,. Only include fields that differ from defaults.
Defaults (omit if unchanged): model=nano2, aspect_ratio=1:1, resolution=0.5K, image_count=1, save_to_assets=true.
| Intent | Add field |
|---|---|
| Portrait | "aspect_ratio":"9:16" (or 2:3 / 3:4) |
| Landscape | "aspect_ratio":"16:9" (or 3:2 / 4:3 / 21:9) |
| Resolution | "resolution":"3K" / "1K" / "0.5K" / "4K" (model-dependent) |
| Multiple images | "image_count":2 (max 4) |
| Image-to-image | "reference_images":["media/img.png"] (local paths auto-converted to base64 by script) |
| Specific model | "model":"nano-pro" |
Minimal example (most requests):
{"prompt":"一只橘猫趴在窗台上晒太阳"}
High-quality example:
{"prompt":"电商主图，护肤品","model":"nano-pro","aspect_ratio":"1:1","resolution":"2K","image_count":2}
Image-to-Image (reference_images)
reference_images accepts three formats — the script handles conversion automatically:
| Format | Example | Notes |
|---|---|---|
| Public URL | "https://cdn.example.com/photo.png" |
Must be direct link (no redirects) |
| Local path | "media/img.png" or absolute path |
Auto-converted to base64 data URI |
| data URI | "data:image/png;base64,..." |
Passed through as-is |
- Local paths are resolved relative to workspace (
~/.deskclaw/nanobot/workspace), or as absolute paths. - Files > 10MB are rejected with an error — ask user to resize.
- Large images may cause submit to return 504 (gateway timeout). This is not a failure — the task is still processing. Run
poll_until_done.pyto get the result. - seedream model has strict content moderation for image-to-image; may return 400.
Commands (copy-paste, do not improvise)
Submit (exec timeout ≥ 90):
python <skill_dir>/scripts/submit.py '<json>'
Poll (exec timeout ≥ 300; skip only if submit already returned image_urls):
python <skill_dir>/scripts/poll_until_done.py <task_id> 240
Default 240s internal wait. progress:50 while processing is normal, not a stall.
Download (supports single URL or JSON array):
python <skill_dir>/scripts/download.py '<url_or_array>' '<short_name>'
Auto saves to $WORKSPACE/outputs/. Do NOT manually set NANOBOT_SESSION_KEY or read auth tokens — the script handles everything.
Present:
Single message(media) with local path(s). Silent until this point.
Fallback (only on failed or content-flagged)
models.py→ pick next model per Default priority.- Re-submit with new model. (+2 calls)
Error Handling
| Case | Action |
|---|---|
| 401/403 | Re-auth |
| 400 (bad aspect/resolution) | Pick a supported value from Models table |
| 429 / quota | 创作点已用完，请前往 DeskClaw 充值后再试～ |
| 504 (submit) | Not a failure — task is processing. Run poll_until_done.py normally |
| 422 upstream_error | Reference image URL unreachable or format unsupported. Use local path instead |
| File > 10MB | Script rejects automatically. Ask user to resize the image |
failed |
Fallback above |
| Poll timeout | Resume poll_until_done same task_id, different max_seconds |
Rules
- Scripts only:
submit.py,poll_until_done.py,download.py,models.py(fallback only). No rawcurl. Always usepython, neverbash. - No pre-read: Do not
read_file SKILL.md/ls scripts//read_file download.py/models.pybefore first submit. - No manual env: Do not read auth tokens, do not set
NANOBOT_SESSION_KEY, do notmkdir. Scripts handle auth + output dirs automatically. - No status text: No "正在生成…" / "请稍等" / progress updates. Silent until
message(media). - JSON compact: No pretty-print, no trailing whitespace.
- Model name in output: Use display_name only (Seedream V5.0 Lite / MiniDesk Pro / MiniDesk 2).