Local HTTP API

Start a server

spum serve model.gguf --gpu --host 127.0.0.1 --port 11436 \
  --context-size 4096 --system-file instructions.txt

The default bind address is loopback. One model is loaded per server process. Stop the foreground process with Control-C. To serve another model concurrently, start another process on a different port and account for the extra memory.

Health and loaded model

curl --fail http://127.0.0.1:11436/health
curl --fail http://127.0.0.1:11436/v1/models

Chat completion

curl --fail http://127.0.0.1:11436/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"Explain numerical aperture."}],"max_tokens":128,"temperature":0.4,"stream":false}'

Streaming

curl --no-buffer --fail http://127.0.0.1:11436/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"Explain image formation step by step."}],"max_tokens":256,"stream":true}'

Streaming uses server-sent events. Clients should assemble returned chunks and handle the final completion signal. A familiar request format does not imply support for every endpoint or field offered by other providers.

Image request

Start a compatible vision model with its matching projector. Supply the image as a base64 data URL inside message content:

{
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe the visible structures."},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,REPLACE_WITH_IMAGE_BYTES"}}
    ]
  }],
  "max_tokens": 192,
  "temperature": 0,
  "stream": false
}

REPLACE_WITH_IMAGE_BYTES is a placeholder, not a usable image. The CLI --image path is simpler for a one-off run. Follow request-size and context limits of your chosen deployment.

Integrate an existing client

Point a compatible chat-completion client at http://127.0.0.1:11436/v1. The server loads its model when started; /v1/models identifies that model. Keep client timeouts appropriate for model loading, image processing and output length.

Supported public endpoints are /health, /v1/models and /v1/chat/completions. Audio transcription, audio synthesis, image generation and video generation endpoints are not present in this release.

Network exposure

Changing --host from loopback makes the service reachable according to the host's network rules. The local server is not a substitute for a managed access-control gateway. Keep loopback for local use; use an authenticated tunnel or separately configured gateway for remote access.