Pay for services

An agent can buy Cue OS services through the CLI or HTTP API. Cue credits use a Cue account. x402 uses a USDC wallet and needs no Cue account or vendor API key. The payment choice is separate from the service and model. Cue credits cover services inside Cue OS; they do not pay arbitrary external x402 providers.

Discover and quote

These commands do not generate or pay:

cue service list --json
cue service inspect image.generate --json
cue service quote image.generate --body '{"prompt":"A small blue ceramic cup on a plain white table","model":"cue-image-1","size":"512x512"}' --json
cue service balance --json

Inspection returns the input schema, example, model catalog, supported payment routes, and recovery information. The current services are image.generate, image.edit, video.generate, speech.generate, transcribe, and search. Each has a quote. Use the selected payment route's schema: some options are available only with credits. A quote with x402.available: false explains the restriction.

service balance checks the configured x402 wallet. A missing wallet returns setup guidance. Configure an existing wallet through X402_BUYER_PRIVATE_KEY and select its network with X402_BUYER_NETWORK: base for Base mainnet or base-sepolia for testing. Keep the key in the process environment, out of prompts and request bodies. The quote's network must match the funded wallet; testnet USDC cannot pay a mainnet service.

Generate and save an image

For x402, the maximum below is a spending limit, not a promise of the price. Check the quote first. The client rejects a higher price before signing.

cue service call image.generate --payment x402 \
  --body '{"prompt":"A small blue ceramic cup on a plain white table","model":"cue-image-1","size":"512x512"}' \
  --max-price-usd 0.02 --wait --download cup.png --json

For credits, use an authenticated Cue profile:

cue service call image.generate --payment credits \
  --body '{"prompt":"A small blue ceramic cup on a plain white table","model":"cue-image-1","size":"512x512"}' \
  --wait --download cup.jpg --json

No client-created conversation is needed. JSON output includes the request ID, result, payment information, and the downloaded file's size, MIME type, and SHA-256. Use a filename suffix matching the returned MIME type.

Edit with reference images

image.edit uses the hosted cue-image-edit-1 model. Supply one to three PNG, JPEG, or WebP files: at most 5 MiB each, 10 MiB combined, and 16 million pixels per image. Animated images and remote URLs are unsupported. The first image sets the output proportions; the provider may resize it. Omit size, quality, resolution, and aspect overrides.

The image command reads local files and saves a recoverable wallet request:

cue image "Change the blue cup to bright red" --image cup.png \
  --model cue-image-edit-1 --payment x402 --max-price-usd 0.02 \
  -o edited.png --json

Use --reference another.png to add a reference. For the generic service API, both payment methods accept the same JSON body:

python3 - <<'PYTHON'
import base64, json
from pathlib import Path
body = {
    "prompt": "Change the blue cup to bright red",
    "model": "cue-image-edit-1",
    "images": [{
        "image_base64": base64.b64encode(Path("cup.png").read_bytes()).decode(),
        "mime_type": "image/png",
    }],
}
Path("edit.json").write_text(json.dumps(body))
PYTHON
cue service inspect image.edit --json
cue service quote image.edit --body-file edit.json --json
cue service call image.edit --payment credits --body-file edit.json \
  --wait --download edited.jpg --json

For a wallet service call, choose --payment x402 --max-price-usd 0.02. Both routes return an asynchronous job. Wallet edits need no Cue account; the result is private and temporary. Save the returned request ID and download the file within seven days. Credit edits retain the Cue image library behavior. If the connection drops, use the history and resume commands below; do not start the edit again.

Recover after a timeout or interruption

Image, video, and speech requests are saved privately before submission and before the signed payment retry. If the terminal closes or the response is lost, open another process and find the original request:

cue service history --json
cue service resume <request-id> --wait --download cup.png --json

Resume retrieves the original result and receipt without authorizing another payment. History shows the last observed state; resume refreshes it. Preserve the local request file: it carries the recovery proof and secret. An x402 recovery does not need the wallet private key. A credit recovery uses the selected Cue account.

Some generation is asynchronous. --wait waits up to 20 minutes, then a processing request can be resumed later. Recovery lasts seven days; download files you want to keep. Temporary job records do not save an asset permanently. If payment is payment_unknown or the outcome is interrupted, resume the original request instead of buying again. Where refunds are enabled, the original request also reports refund progress and the return transaction. Search and transcription return directly and do not currently advertise this recovery contract.

Audio prices and limits

Speech quotes scale with text length and model. Short requests retain a minimum price. Wallet limits are 20,000 characters for Gemini, 4,096 for OpenAI, 5,000 for ElevenLabs, and 1,024 for Z.AI. Inspect the service for supported models and voices. Credit estimates can change with actual provider usage.

Wallet transcription accepts audio_base64 containing a file up to 20 MB and 60 decoded seconds. The server measures the audio before payment and quotes a one-minute model tier. URLs, raw audio hints, custom prompts, translation, and speaker separation require credits. The schema and quote explain these limits.

Use HTTP without Cue CLI

The public catalog is api.cueos.ai/api/v1/services. It returns route paths, request schemas, examples, quotes, and recovery metadata without authentication. An independent x402 client can:

Read the catalog and POST the intended input to the service's quote_path.
POST the same input to its x402 payment path and read PAYMENT-REQUIRED.
Check network, asset, and amount, then sign and retry with Payment-Signature.
Verify PAYMENT-RESPONSE and save the result or recover the original request.

Use an x402 SDK for signing. For recovery, generate a UUID request ID and an independent random secret, send them in the headers named by the catalog, and save the body, ID, secret, and signed payment before sending the paid request. GET the advertised status_path with the original Payment-Signature and X-Cue-Recovery-Token. Keep those values private. Status reports the result and a short-lived download URL when it is ready.

For a local test server, inspect, quote, and x402 calls accept --endpoint. Credit calls use the endpoint configured in the selected Cue profile.