@heyamiko/amiko-cli 0.11.0-beta.3 → 0.12.0-beta.3

package/README.md

@@ -116,6 +116,100 @@ Pricing is OpenAI pass-through × 1.30 markup, paid in AMIKO at the live AMIKO/U
 
 Image generation typically takes 20–60s. In non-TTY environments (agents, piped shells), the CLI prints a `…still working (Ns elapsed)` tick to stderr every 3s so the parent process can tell it hasn't hung.
 
+## Create Studio
+
+The CLI half of the platform's Create Studio. `amiko create` generates media through Amiko's own authenticated endpoints (not the raw MPP pay-per-call surface `amiko markets` uses). Generation runs **asynchronously** and is **charged on success** from your twin's wallet — a failed or timed-out generation is never billed, and there's no up-front payment.
+
+```bash
+amiko create image "a sunset over mountains"                    # default gpt-image-2, 1:1
+amiko create image "logo" --aspect 16:9 --model gpt-image-2     # widescreen
+amiko create video "a whale in space" --resolution 768P --seconds 6
+amiko create tts "Hello world" --voice 21m00Tcm4TlvDq8ikWAM
+amiko create music "lo-fi chill beat" --duration 30000
+amiko create music --lyrics "..." --instrumental               # instrumental
+amiko create sfx "thunder and heavy rain" --duration 5
+amiko create image "banner" --raw                               # raw JSON
+```
+
+Modes: `image`, `video`, `tts`, `music`, `sfx` (mirrors the platform Create Studio).
+
+**Common flags (all subcommands):**
+
+| Flag | Description |
+|------|-------------|
+| `--token <symbol>` | Charge token: `AMIKO`, `USDC`, `USDT`, `SOL` (default: auto, AMIKO-first) |
+| `--yes` | Skip the pre-spend confirmation (required in non-interactive shells) |
+| `--raw` | Output the raw job result as JSON |
+
+**`amiko create image <prompt>`**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model <model>` | `gpt-image-2` | Image model |
+| `--aspect <ratio>` | `1:1` | Aspect ratio: `1:1`, `16:9`, `9:16`, `4:3`, `3:4` |
+
+**`amiko create video <prompt>`**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model <model>` | `MiniMax-Hailuo-2.3-Fast` | Video model |
+| `--resolution <res>` | `768P` | `512P`, `720P`, `768P`, `1080P` |
+| `--seconds <n>` | `6` | Clip length: `6` or `10` |
+| `--aspect <ratio>` | — | Aspect ratio (provider-dependent) |
+| `--first-frame <url>` | — | Image-to-video: first frame URL or data URI |
+
+**`amiko create tts <text>`**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model <model>` | `eleven_multilingual_v2` | TTS model id |
+| `--voice <voiceId>` | `21m00Tcm4TlvDq8ikWAM` | Voice id |
+
+**`amiko create music [prompt]`** — pass a prompt and/or `--lyrics`
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model <model>` | `music-2.6` | `music_v1`, `music-2.6`, `music-cover` |
+| `--lyrics <lyrics>` | — | Lyrics (optional) |
+| `--duration <ms>` | — | Length in milliseconds |
+| `--instrumental` | — | Instrumental (no vocals) |
+
+**`amiko create sfx <text>`**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--duration <seconds>` | — | Clip length in seconds |
+
+### How it works (and getting the result)
+
+**By default the command returns immediately** with a **job id** and `status: PENDING` — it does **not** block for the whole generation. It prints how to check the result and a rough ETA. This keeps agents/scripts from being held for 60s–9min.
+
+```
+$ amiko create image "a whale in space" --yes
+Submitted — job aX9k…
+Status: PENDING — generating in the background
+Check result: amiko create status aX9k…
+Usually ready in ~15–60s — charged only on success.
+```
+
+Rough ETAs: image ~15–60s, video ~2–9 min, music ~30–120s, tts/sfx ~5–20s.
+
+Retrieve the finished asset with:
+
+```bash
+amiko create status <jobId>   # re-query that job (queryable ~24h)
+amiko create media            # list your recent generations (permanent)
+amiko create media --service video --limit 5
+```
+
+- **`amiko create status <jobId>`** — re-polls the job once; prints `PROCESSING`, or the asset + charge when done. Jobs stay queryable for ~24h.
+- **`amiko create media`** — lists your recent Create Studio generations (URL, type, model, prompt, date). `--service <type>` filters, `--limit <n>` caps (max 50), `--raw` for JSON. Use this once a job id has expired, or just to browse.
+- **Web:** `https://platform.heyamiko.com/media`
+
+**`--wait`** — if you'd rather block until it finishes and print the asset inline (e.g. an interactive terminal), pass `--wait`. It polls (10 min cap for video, 5 min otherwise) with a `…still generating (Ns)` tick; on timeout it falls back to the job-id + retrieval hint above. `--raw` prints the full job result as JSON either way.
+
+> `amiko markets image` still exists and is unchanged — it's the direct MPP pay-per-call path (pre-pay in AMIKO). Use `amiko create` for the Create Studio experience (async, charge-on-success); use `amiko markets` for raw MPP endpoints.
+
 ## Amazon
 
 ```bash