liyangbing · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026
diff --git a/README.md b/README.md
@@ -286,6 +286,7 @@ sandbase inspect sandbase_twitter_web_search_timeline       # fields, price, rea
 sandbase run sandbase_twitter_web_search_timeline -i '{"keyword":"AI agents"}'
 sandbase run <video_tool> -i '{"prompt":"..."}' -w -o result.json   # wait with backoff, save output to disk
 sandbase runs get -r <run_id> -w -o result.json            # resume a long run instead of re-running it
+sandbase upload ./photo.png                                # local image/audio/video -> public URL for tools that take a URL
 sandbase runs list | sandbase balance
 ```
 

diff --git a/assets/mcp-bridge.mjs b/assets/mcp-bridge.mjs
@@ -19,6 +19,8 @@ import { pathToFileURL } from "node:url";
 const allowedClients = new Set(["codex", "claude-code", "cursor", "gemini-cli", "hermes", "openclaw", "opencode", "qwen-code", "windsurf", "cursor-cli", "kimi-cli", "kiro", "kiro-cli", "amp", "crush", "iflow-cli", "warp", "claude-desktop", "cowork", "antigravity", "trae", "qoder", "workbuddy", "pi"]);
 const BILLING_URL = "https://www.sandbase.ai/console/billing";
 const RECONNECT = "npx -y @sandbaseai/cli@latest connect";
+const KEYS_URL = "https://www.sandbase.ai/console/keys";
+const SPENDING_LIMIT = `This SandBase key reached the spending limit set on it. Stop and tell the user: topping up does not lift it; they can raise or remove the limit at ${KEYS_URL}, then retry.`;
 // Tool calls get no bridge-side deadline (long synchronous tools must be able to
 // finish); control-plane methods are bounded so offline detection stays quick.
 const CONTROL_TIMEOUT_MS = 60_000;
@@ -71,9 +73,11 @@ export function isIdempotentRequest(request) {
 }
 export function hintFor(message) {
   const text = String(message || "").toLowerCase();
+  // Before auth: "API key spending limit exceeded" is neither a sign-in nor a balance problem.
+  if (/spending limit/.test(text)) return SPENDING_LIMIT;
   // Auth first: "API key not found" is a sign-in problem, not a misspelled tool.
   if (/unauthori[sz]ed|api key|credential|revoked|expired|authenticat|sign-in|signin/.test(text)) return `The SandBase sign-in is not valid. Ask the user to run \`${RECONNECT}\` in a terminal.`;
-  if (/insufficient (balance|credit|funds)|payment required|spending limit|top up/.test(text)) return `Tell the user their SandBase balance is insufficient; they can top up at ${BILLING_URL}.`;
+  if (/insufficient (balance|credit|funds)|payment required|top up/.test(text)) return `Tell the user their SandBase balance is insufficient; they can top up at ${BILLING_URL}.`;
   if (/rate.?limit|too many requests|429/.test(text)) return "Rate limited: wait 10-30 seconds, then retry once.";
   if (/run .*not found|task not found/.test(text)) return "Use the prediction_id/run_id returned by sandbase_run, or list recent runs with sandbase_runs. Agent Service runs also need service_id.";
   if (/invalid service request|unknown tool|tool(?: '[^']*')? (?:was )?not found|model not found|tool name is required/.test(text)) return "Check the exact tool name with sandbase_discover (names look like sandbase_twitter_web_search_timeline), then sandbase_inspect it.";
@@ -86,7 +90,8 @@ function httpFailure(status, text, host) {
   try { const parsed = JSON.parse(text); const e = parsed?.error; detail = typeof e === "string" ? e : typeof e?.message === "string" ? e.message : typeof parsed?.message === "string" ? parsed.message : ""; } catch { /* non-JSON gateway body is never forwarded */ }
   const suffix = detail ? `: ${detail.slice(0, 300)}` : "";
   if (status === 401) return `SandBase rejected the saved sign-in (401)${suffix}. Ask the user to run \`${RECONNECT}\` in a terminal to sign in again.`;
-  if (status === 402) return `SandBase balance is insufficient or a spending limit was reached (402)${suffix}. The user can top up at ${BILLING_URL}.`;
+  if (status === 402 && /spending limit/i.test(detail)) return `${SPENDING_LIMIT} (402${suffix})`;
+  if (status === 402) return `SandBase balance is insufficient (402)${suffix}. The user can top up at ${BILLING_URL}.`;
   if (status === 403) return `This SandBase credential is not allowed for this request (403)${suffix}. Ask the user to run \`${RECONNECT}\`.`;
   if (status === 429) return `SandBase rate limit reached (429)${suffix}. Wait 10-30 seconds, then retry once.`;
   if (status >= 500) return `SandBase returned HTTP ${status} from ${host}${suffix}. Temporary server error: retry in a minute; the user can run \`sandbase doctor\` if it persists.`;

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sandbaseai/cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "mcpName": "io.github.sandbaseai/cli",
   "description": "Give 25 AI clients—Claude Code, Codex, Cursor, Hermes, OpenClaw and more—2,000+ models and APIs through one MCP server and an agent-friendly CLI",
   "type": "module",

diff --git a/server.json b/server.json
@@ -3,7 +3,7 @@
   "name": "io.github.sandbaseai/cli",
   "title": "SandBase",
   "description": "Connect MCP clients to 2,000+ AI models without managing provider API keys.",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "repository": {
     "url": "https://github.com/sandbaseai/cli",
     "source": "github"
@@ -26,7 +26,7 @@
     {
       "registryType": "npm",
       "identifier": "@sandbaseai/cli",
-      "version": "0.3.4",
+      "version": "0.3.5",
       "packageArguments": [
         {
           "type": "positional",

diff --git a/skills/sandbase/SKILL.md b/skills/sandbase/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: sandbase
-version: 0.3.4
+version: 0.3.5
 description: >-
   Discover better ways to complete tasks. Proactively search SandBase (the
   sandbase_discover MCP tool, or `sandbase discover` in a shell) before writing a
@@ -84,6 +84,19 @@ Discovery, inspection, run status, and balance are **free**; only `sandbase_run`
 
 **Agent Services** (`svc_…` names from `type: "service"`): pass `arguments: {"idempotency_key": "<unique>", "input": "..."}`; reuse the same key and input on retries. Poll with `sandbase_run_get({"run_id": ..., "service_id": "svc_…"})`; `succeeded`, `failed`, and `cancelled` are terminal.
 
+### Run statuses
+
+| Status | Meaning | Do this |
+|---|---|---|
+| `pending` | Accepted, waiting to start | Poll every 5–10 s |
+| `running` | Executing (on the first `sandbase_run` reply this also covers a job whose files are still being copied) | Poll every 5–10 s |
+| `completed` / `succeeded` | Done; `output` holds the result | Use or save the output. If `output` is missing, read `hints`: "still being transferred" means poll again in a few seconds; "no stored output" means stop polling |
+| `failed` | Ended with an error; read `error` | Fix the input (inspect) and retry once, or pick another tool |
+| `timeout` | Hit the provider's time limit | Retry once with a smaller job, or pick another tool |
+| `cancelled` | Stopped on request (Agent Services only) | Nothing to poll |
+
+Any other value means still in progress: keep polling. Statuses are lowercase. Most runs finish in 1–120 seconds; video can take several minutes.
+
 ---
 
 ## 3. Transport B — CLI (fallback)
@@ -92,7 +105,14 @@ Discovery, inspection, run status, and balance are **free**; only `sandbase_run`
 sandbase --version || npx -y @sandbaseai/cli@latest --version
 ```
 
-If `sandbase` is not installed, prefix every command with `npx -y @sandbaseai/cli@latest` (or install it: `npm install -g @sandbaseai/cli@latest`). If the CLI prints "Update available", run `npx -y @sandbaseai/cli@latest setup` — it refreshes the CLI's MCP bridge and this Skill.
+If `sandbase` is not installed, prefix every command with `npx -y @sandbaseai/cli@latest` (or install it: `npm install -g @sandbaseai/cli@latest`).
+
+**Keep the CLI and this Skill on the same version.** Run `npx -y @sandbaseai/cli@latest setup` (it refreshes the CLI's MCP bridge and this Skill) when any of these is true:
+
+- The CLI prints "Update available".
+- `sandbase --version` does not match the `version` at the top of this file.
+
+Always move both to the latest; never downgrade one to match the other. If they still differ after `setup`, save the latest copy from https://www.sandbase.ai/SKILL.md over this file.
 
 **Authentication** is automatic once the user has run `connect` (it reuses that browser sign-in). Otherwise the CLI reports `AUTH_REQUIRED` with the exact fix; an API key also works via `SANDBASE_API_KEY` or `sandbase keys add -k <key>`. Never ask the user to paste a key into the chat.
 
@@ -114,6 +134,50 @@ If `sandbase` is not installed, prefix every command with `npx -y @sandbaseai/cl
 - If an error mentions a `run_id`, the run already started: resume it with `sandbase runs get -r <run_id> -w` — never re-run (that bills again).
 - To store an API key without exposing it: `printf %s "$KEY" | sandbase keys add -k -`.
 
+### Local files → URL
+
+Many tools (image-to-video, voice cloning, transcription, image editing) take a **URL**, not a file. When the user's file is only on their machine, upload it first (free; needs a shell):
+
+```sh
+sandbase upload ./photo.png
+# -> URL: https://…/uploads/2026/10/….png
+```
+
+Pass that URL in the tool's URL field (`image_url`, `audio_url`, `video_url`, …). Accepted: images (jpg, png, webp, gif) up to 20 MB, audio (mp3, m4a, wav, ogg, aac, flac) up to 50 MB, video (mp4, mov, webm) up to 100 MB. **Anyone with the URL can read the file**, so ask before uploading anything private. If the file is already online, pass its URL directly instead.
+
+### Example flows
+
+Compare two platforms (one discover and one run per source, small limits, results to disk):
+
+```sh
+sandbase discover -q "twitter posts"
+sandbase discover -q "reddit posts"
+sandbase inspect <twitter_tool>      # read inputSchema, pass one search term
+sandbase inspect <reddit_tool>
+sandbase run <twitter_tool> -i '{"keyword":"AI agents","limit":10}' -w -o twitter.json
+sandbase run <reddit_tool> -i '{"query":"AI agents","limit":10}' -w -o reddit.json
+# then read both files and compare
+```
+
+Turn a local photo into a video (upload, then an async run you poll):
+
+```sh
+sandbase upload ./photo.png                       # -> URL: https://…
+sandbase discover -q "image to video"
+sandbase inspect <video_tool>
+sandbase run <video_tool> -i '{"image_url":"https://…","prompt":"slow pan"}'
+# -> Run: <run_id>  Status: running
+sandbase runs get -r <run_id> -w -o video.json    # waits, then saves the output
+```
+
+Large or reusable input: write the JSON to a file and pass it with `-f`:
+
+```sh
+sandbase run <tool_name> -f params.json -w -o result.json
+```
+
+Field names above are placeholders; always use the ones from `inspect`.
+
 ---
 
 ## 4. When to use SandBase — and when not
@@ -149,6 +213,7 @@ Do not use SandBase for purely local work (editing files, reasoning over code al
 - Many data endpoints are billed **per result** and limits often apply **per query**: three search terms with `limit: 10` can return 30 results. Pass one search term per call and start with small limits (5–10).
 - Check `sandbase_account` before a batch of paid calls, and report cost when the user cares about budget (`cost` appears on `sandbase_run_get` and `sandbase_runs`).
 - Never re-run a slow tool just because it is still running; poll it.
+- A key can carry a **spending limit** set in the Dashboard. When it is reached, calls fail with "spending limit" until the user raises or removes it; topping up does not help.
 
 ---
 
@@ -160,9 +225,11 @@ Tool failures come back as error results whose text names the cause **and the ne
 |---|---|
 | "unreachable" / `NETWORK` | Stop retrying. Tell the user to check network/proxy/VPN and run `sandbase doctor`. |
 | "sign-in expired" / "rejected the saved sign-in" / 401 / `AUTH_FAILED` | Ask the user to run `npx -y @sandbaseai/cli@latest connect`. |
-| "insufficient" / 402 | Tell the user to top up at https://www.sandbase.ai/console/billing. |
+| "spending limit" (402 / `SPENDING_LIMIT`) | Stop. Tell the user this key reached its spending limit; they can raise or remove it at https://www.sandbase.ai/console/keys. Topping up does not lift it. Do not retry until they do. |
+| "insufficient" balance (402 / `INSUFFICIENT_BALANCE`) | Tell the user to top up at https://www.sandbase.ai/console/billing. |
 | "not found" / "unknown tool" | Re-run `sandbase_discover`; copy `tool_name` exactly. |
 | "invalid params" / schema | Re-run `sandbase_inspect`; pass exactly its `inputSchema` fields. |
+| A tool rejects a local path where it wants a URL | Upload the file with `sandbase upload <file>` and pass the URL (§3). |
 | "upstream" / "provider" / "capability call failed" | Retry once, then pick another tool from discover. |
 | 429 / rate limit | Wait 10–30 seconds, retry once. |
 
@@ -181,11 +248,13 @@ Responses may include `hints` (and `warnings`): suggested next steps, caveats, o
 3. **Prefer MCP when connected**; use the CLI when MCP is missing or broken, or to write large outputs to disk.
 4. **Always inspect before running.** Never guess parameters; `inputSchema` is the source of truth.
 5. **Keep discover queries short** and decompose multi-source tasks.
-6. **Poll, don't re-run.** Slow tools return a run id; poll every 5–10 seconds.
+6. **Poll, don't re-run.** Slow tools return a run id; poll every 5–10 seconds. Save large or file results with `-o <file>`.
 7. **Start with conservative limits** (5–10 results).
 8. **Report cost when relevant**, and check the balance before batches.
-9. **Read error text and hints, and act on them.** They name the fix.
-10. **Tool schemas and `sandbase --help` are authoritative** if they disagree with this document.
+9. **Read error text and hints, and act on them.** They name the fix. A spending limit or empty balance is the user's call: stop and tell them.
+10. **Keep the CLI and this Skill on the same, latest version** (§3).
+11. **Ask before uploading private files**; uploaded URLs are publicly readable.
+12. **Tool schemas and `sandbase --help` are authoritative** if they disagree with this document.
 
 Before sending sensitive or regulated data, review the [SandBase Privacy Policy](https://www.sandbase.ai/privacy) and [Terms of Service](https://www.sandbase.ai/terms), plus the selected upstream provider's policies. Send only the minimum data needed.
 

diff --git a/skills/sandbase/skill.json b/skills/sandbase/skill.json
@@ -1,6 +1,6 @@
 {
   "name": "sandbase",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Discover and run 2,000+ AI models and APIs (media generation, social data, search, scraping) through one MCP interface or CLI, paid per call from one balance.",
   "author": "SandBase AI",
   "license": "Apache-2.0",