# Scalarware API — complete agent reference Use this document when integrating Scalarware directly or through an AI agent. Installing a skill is optional. ## Authentication Base URL: `https://scalarware.com/api/v1` All execution and job endpoints require: `Authorization: Bearer $SCALARWARE_API_KEY` Never expose the Scalarware key in browser code, public source code, logs, or generated output. Keys carry scopes. `inference:read` and `inference:write` cover models, chat and media. `compute:read` covers `GET /wallet`, `GET /compute/offers` and reading deployments. `compute:write` is required to quote, launch or destroy a deployment, and a key that lacks it receives `401 unauthorized`. Create a key with compute scopes in the dashboard under API keys. Launching spends real credit from the workspace balance. Check `GET /wallet` before quoting: `balance_microusd - reserved_microusd` must cover `hourly_price x runtime_hours`, or the launch returns `402 insufficient_balance`. ## Language inference - List live models: `GET /models` - OpenAI-compatible inference: `POST /chat/completions` Chat body fields include `model`, `messages`, and optional `stream`. Use an exact model ID returned by `GET /models` — ids are the market's canonical slugs, for example `z-ai/glm-5.3-flash`, and `GET /models` is ordered by real weekly usage so the first entries are the models people are actually running. Inference is billed at the published model rate with no Scalarware markup, taken from the workspace balance as each request completes. A request with no available balance is refused with `402 insufficient_balance`, so top up before a long run. Because a request is priced only once the model answers, the last one can take the balance slightly negative. That is recorded as a debt and cleared by the next top-up; no further work runs until the balance is positive again. GPU runtime is charged every minute while a machine is up, and a machine whose workspace runs out of credit is stopped automatically within about a minute. Reasoning models spend completion tokens on internal reasoning before answering. With a small `max_tokens` they can return empty content while still consuming tokens. Allow a few hundred tokens when calling one. ### Calling inference from a Scalarware GPU A machine launched from a template already holds its own scoped key. Nothing needs to be installed or pasted: ```bash source /root/.config/scalarware/env # sets SCALARWARE_API_KEY and _BASE_URL curl -s -X POST "$SCALARWARE_API_BASE_URL/chat/completions" \ -H "Authorization: Bearer $SCALARWARE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"z-ai/glm-5.3-flash","messages":[{"role":"user","content":"hello"}]}' ``` That key carries `inference:read` and `inference:write` only — it can run models and media jobs but cannot launch or destroy compute, and it expires when the deployment does. The same call works for `/images/generations` and `/videos/generations`. ## GPU compute and deployments - Check available credit: `GET /wallet` - Discover live GPU capacity: `GET /compute/offers` - List launchable templates: `GET /templates` - Every offer reports `network_down_mbps`. Scalarware lists only machines at 1 Gbps or faster and RTX PRO 6000 or better, so anything returned can hold a modern model and pull its weights quickly. - Machines a template can actually run on: `GET /compute/offers?template=` returns only hardware that template is tested on, priced at the template rate. Use this before quoting so you never offer a GPU that cannot launch it. - Request a five-minute quote: `POST /deployments/quote` with `template_id` and `runtime_hours` (1, 4, 8, or 24). Add `offer_id` from the filtered offers list to quote one specific machine; omit it and the cheapest eligible machine is quoted. The quote echoes the `offer_id` it locked in. - List deployments: `GET /deployments` - Launch: `POST /deployments` with `quote_id`, `confirmation: "LAUNCH"` and `customer_ssh_public_key`. Templates where `GET /templates` reports `weightsManaged` need nothing else: Scalarware supplies the model weights over expiring signed links and places no credential on the machine. Every other template additionally requires `hf_token` and `accepted_model_terms: true` from a Hugging Face account that has accepted that model's licence. - Inspect connection and tunnel command: `GET /deployments/{id}` `status` describes the machine and `setup` describes the model on it. They move independently on purpose: the moment `status` is `running` the machine is yours, SSH is open and billing has started — but a template's weights are tens of GB and keep downloading after that. Do not wait for `setup.ready` before connecting; do wait for it before calling the model's port. ```json { "status": "running", "setup": { "state": "downloading", "ready": false, "progress": 38, "detail": "Downloading model weights (16G, 3 of 8 files)" } } ``` `setup.state` moves through `preparing`, `downloading`, `starting`, `ready`, and `failed`. Do not poll in silence. `GET /deployments/{id}/wait?since=` blocks until the phase changes or ~25 seconds pass, and every response carries a `tell_user` line. Loop on it and relay each line as it arrives: ```bash state=provisioning while :; do r=$(curl -s -H "Authorization: Bearer $SCALARWARE_API_KEY" \ "$BASE/deployments/$ID/wait?since=$state") echo "$r" | jq -r .tell_user # say this to the user state=$(echo "$r" | jq -r .setup.state) [ "$state" = ready ] || [ "$state" = failed ] && break done ``` A first launch takes roughly 5 to 15 minutes and is indistinguishable from a broken machine if nobody is told what is happening. The launch response also returns `next_action` with the same instruction. - Destroy: `DELETE /deployments/{id}` with `confirmation: "DESTROY"` GPU offer prices returned by `/compute/offers` and deployment quotes are final Scalarware customer prices. Supplier costs and internal margin calculations are not part of the public API contract. The model service remains private inside the rented GPU. Scalarware returns a customer-direct SSH tunnel command. Runtime is capped and unused reserved credit is released when the deployment is destroyed. ## Workspace endpoints - `GET /keys`, `POST /keys`, `DELETE /keys/{id}` - `GET /wallet` - `GET /usage?limit=50` Workspace endpoints require the signed-in dashboard session. Newly created API key tokens are returned once. ## Discover supported media models `GET /catalog/search?modality=image` `GET /catalog/search?modality=video` Optional query: `q=`. Each result contains `id`, `modality`, `description`, `price_tiers`, `billing_metric`, and the authoritative `input_schema`. Fetch this endpoint before constructing model-specific input. Do not submit unlisted models or fields outside the returned schema. ## Create an image job `POST /images/generations` ```json { "model": "google/nano-banana-2", "input": { "prompt": "Editorial product photograph", "resolution": "1K" }, "wait_seconds": 10, "cancel_after_seconds": 300 } ``` ## Create a video job `POST /videos/generations` ```json { "model": "alibaba/wan-3", "input": { "prompt": "A cinematic aerial shot over the coast", "duration": 5, "resolution": "1080p", "aspect_ratio": "16:9" }, "cancel_after_seconds": 1800 } ``` Both create endpoints return an asynchronous Scalarware job. Save its `id` and `poll_url`. ## Job lifecycle - Poll: `GET /media/jobs/{id}` - Cancel: `DELETE /media/jobs/{id}` - Download: `GET /media/jobs/{id}/output/{index}` Poll until `status` is `succeeded`, `failed`, or `canceled`. Use the same Scalarware key for every operation. Output URLs are authenticated Scalarware URLs. Do not attempt to construct or expose an upstream provider URL. ## Supported image models - `google/nano-banana-2`: requires `prompt`; supports `resolution`, `image_input`, `aspect_ratio`, `image_search`, `google_search`, `output_format`. - `openai/gpt-image-2`: requires `prompt`; supports `quality`, `input_images`, `number_of_images`, `aspect_ratio`, `background`, `moderation`, `output_format`, `output_compression`, `user_id`. - `bytedance/seedream-5-lite`: requires `prompt`; supports `size`, `image_input`, `max_images`, `sequential_image_generation`, `aspect_ratio`, `output_format`. - `xai/grok-imagine-image`: requires `prompt`; supports `image`, `aspect_ratio`. ## Supported video models - `alibaba/wan-3`: requires `prompt`; supports `image`, `negative_prompt`, `resolution`, `aspect_ratio`, `duration`, `enable_prompt_expansion`, `seed`. - `prunaai/p-video`: requires `prompt`; supports `image`, `last_frame_image`, `audio`, `duration`, `resolution`, `draft`, `fps`, `aspect_ratio`, `save_audio`, `prompt_upsampling`, `seed`. - `xai/grok-imagine-video-1.5`: requires `prompt` and `image`; supports `duration`, `resolution`, `aspect_ratio`. - `xai/grok-imagine-video`: requires `prompt`; supports `image`, `video`, `duration`, `resolution`, `aspect_ratio`. - `kwaivgi/kling-v3-omni-video`: requires `prompt`; supports `mode`, `duration`, `start_image`, `end_image`, `reference_video`, `reference_images`, `aspect_ratio`, `generate_audio`, `keep_original_sound`, `video_reference_type`, `multi_prompt`. - `kwaivgi/kling-v3-motion-control`: requires `image` and `video`; supports `prompt`, `mode`, `keep_original_sound`, `character_orientation`. The live catalog's `input_schema` is authoritative for enums, defaults, limits, and file URI fields. ## Pricing and wallet behavior Scalarware calculates a maximum estimate before creating a paid prediction and reserves that amount. Completed jobs settle using the displayed output-unit rate and actual output count or duration when available; unused credit is released. Responses include `estimated_microusd`, `billed_microusd`, and `currency`. Scalarware verifies its configured rate against the current public pricing source before each paid creation. If verification fails or pricing changed, it returns `pricing_refresh_required` and creates no prediction. ## Errors Errors use `{ "error": { "code": "...", "message": "..." } }`. - 400: invalid request or unsupported model - 401: missing or invalid Scalarware key - 402: insufficient wallet credit - 404: job or output not found - 409: idempotency or job-state conflict - 429: rate or budget limit reached - 502/503: execution route unavailable ## Connecting your coding agent Every agent below works against this same REST API. Two things are always needed: the key in the environment, and this document (or a skill) in the agent's context. ```bash export SCALARWARE_API_KEY=scalar_live_... # Dashboard -> API keys ``` There is no Scalarware CLI and no MCP server yet. Agents that expect an MCP endpoint should be pointed at this document instead. ### Claude Code and Codex — skills ```bash curl -fsSL https://scalarware.com/skills/install.sh | bash ``` Installs `scalarware-media` (generate images and video) and `scalarware-augustus` (publish finished media into an Augustus character's Ready pool) into `~/.claude/skills` and `~/.codex/skills`. Both are already present on any GPU launched from a Scalarware template, so this is only for your own machine. The agent loads a skill when the task matches its description; no further configuration is needed. ### Cursor Cursor does not read the skills folders. Add a project rule instead — create `.cursor/rules/scalarware.mdc`: ``` --- description: Scalarware API for models, media and GPU compute alwaysApply: false --- Use the Scalarware API for image, video, language inference and GPU rentals. Base URL https://scalarware.com/api/v1, bearer $SCALARWARE_API_KEY. Full reference: https://scalarware.com/llms-full.txt — fetch it before calling. ``` ### VS Code (GitHub Copilot) Add `.github/copilot-instructions.md` to the repository with the same three lines. Copilot reads it automatically for every request in that workspace. ### Kilo Code, Cline, Roo and other rules-based agents These read a rules file from the project root. Put the same instruction in `.kilocode/rules/scalarware.md` (Kilo), `.clinerules` (Cline), or the equivalent, and set `SCALARWARE_API_KEY` in the environment. ### Anything else Give the agent this URL: `https://scalarware.com/llms-full.txt`. It is written to be read start to finish by a model and contains every endpoint, field and limit.