# Customer workflows

Configure the staging CLI as described in [the skill](../SKILL.md).

## Discover and budget

```sh
heimdall-staging models list --json
heimdall-staging models show MODEL_ID --json
heimdall-staging models endpoints MODEL_ID --json
heimdall-staging key --json
heimdall-staging credits --json
```

Replace `MODEL_ID` with an exact catalogue id. Inspect the selected endpoint's
modalities, supported parameters, price units, limits, and capability evidence.
Price units differ across models: token, character, image, audio/video duration,
and mesh prices cannot be compared as if they were the same unit.

A spending key pays for inference. Key administration requires a management key,
which cannot pay for inference. Management keys operate within their own workspace.
The browser's account controls create management keys, select organizations and
workspaces, and configure limits/expiry. Do not replace a working spending profile
with a management key just to inspect inference access. Use the existing secret
injection mechanism for each task's credential.

## Funding and receipts

`deposits stripe --json` and `deposits x402 --json` read public rail terms, including
whether a rail is enabled. They do not deposit funds. Card checkout starts in the
browser at https://staging.impossiblecarrot.cc/account?tab=credits. For crypto and signed
payment authorizations, read https://staging.impossiblecarrot.cc/docs/guides/deposits.md.
`deposits create` submits x402 authorizations; it does not sign for a wallet. A 402
payment offer is not a completed deposit. Confirm funding through `credits --json`
after the required chain confirmations.

Use `activity --json` and `generations show GENERATION_ID --json` for API receipts;
`log --json` is local history and is not the complete account ledger. Charges and
usage fields depend on the API dialect; do not assume every response contains
`usage.cost`. The account pages expose the broader billing history.

## Inference

Use `--help` for file formats and controls. These commands support `--json`:

| Task                | Command                                               | Contract                                                                    |
| ------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------- |
| Chat, vision, tools | `chat --model MODEL_ID "PROMPT"`                      | `/docs/api/chat.md`; use the API for message parts not exposed by CLI flags |
| Text completion     | `complete --model MODEL_ID "PROMPT"`                  | `/docs/api/completions.md`                                                  |
| Embeddings          | `embed --help`                                        | `/docs/api/embeddings.md`                                                   |
| Transcription       | `transcribe --help`                                   | `/docs/api/transcriptions.md`; multipart audio                              |
| Image generation    | `image --model MODEL_ID --out result.png "PROMPT"`    | `/docs/api/images.md`; reference `POST /images`                             |
| Video               | `videos create --input request.json --out result.mp4` | `/docs/api/videos.md`                                                       |
| Mesh                | `meshes create --input request.json --out result.glb` | `/docs/api/meshes.md`                                                       |

Resolve contract paths against https://staging.impossiblecarrot.cc. Read the
specific reference before writing `request.json`, especially for reference inputs,
output sizes, adapters, or mesh repair. Image output is written to `--out`; its JSON
result omits the base64 payload. Chat under a terminal can run an interactive loop;
for a one-shot agent command redirect stdin from `/dev/null` or pipe the prompt.

Reranking uses `POST /rerank` and speech synthesis uses `POST /audio/speech`.
Read `/docs/api/rerank.md` and `/docs/api/speech.md`. Neither has a dedicated CLI
command. The existing `heimdall-staging api /rerank -X POST --input request.json --yes`
can submit JSON and print the response, but this generic command reads only
`HEIMDALL_STAGING_API_KEY`, not the saved login profile, and has no `--json` flag.
For binary speech output, streaming, multipart requests, or other SDK features,
use the documented HTTP/client examples with credentials supplied securely by the
runtime. Do not print or extract a saved key to turn it into a command-line argument.

## Media recovery and errors

Save the returned job id. `videos show JOB_ID --out result.mp4` or
`meshes show JOB_ID --out result.glb` resumes waiting on that job. Timeout or
interruption leaves it running. Do not repeat creation to recover a poll failure.
Downloads can be single-use; a failed transfer may consume the asset. Inspect the
job and any partial file before another attempt. Existing destinations are refused.

For HTTP API errors, branch on `error.metadata.error_type` when supplied rather than
matching prose. CLI failures can wrap the message in the CLI's JSON error shape;
check its exit code as well. Missing/expired/revoked credentials require reconnection;
insufficient balance or a spent key limit requires funding or an authorized limit
change. Neither is a transient error to retry. Respect `Retry-After` and bound retries
for read/poll failures. Do not blindly resubmit a paid request after an ambiguous
network failure. Inspect activity and job ids first.

Responses clients send full conversation state: stored-response chaining, background
execution, and built-in server tools are unsupported. Messages uses its own events.
Consult `/docs/migration.md` before assuming OpenAI or OpenRouter feature parity.