Cogs

Cogs API — GPU model hosting

Run an arbitrary Cog container as an autoscaling, scale-to-zero inference endpoint. Register any compliant image once, or use POST /api/cogs/run to atomically ensure a vetted template and queue work in one call. Low traffic can use serverless workers; sustained demand promotes to a warm pod through the GPU router shared with ComfyUI. The idle reaper checks active predictions before terminating the worker, and every response exposes an immediate sleep path. Comfy graphs use template:name references, so durable workflows never contain pod ids or endpoints. Media travels as HTTPS URLs or data URIs, making Pocket TTS, Fish Speech, Audex speech-to-speech, image, video, and 3D Cogs first-class.

basehttps://app.nz
GET/api/cogs/configGPU hardware catalogue, starter templates, output kinds, markuppublicGET/api/cogsList your registered modelsAPI keyPOST/api/cogsRegister a model (name, image, hardware, schema, idleSeconds, minVramGb)API keyPOST/api/cogs/runEnsure a vetted template or use modelId, then queue inference with scale-to-zero lifecycle metadataAPI keyPOST/api/cogs/spaces/importDiscover a Gradio Hugging Face Space and deploy its published image with generated API/UI and scale-to-zeroAPI keyGET/api/cogs/{id}Model detail plus its 20 most recent predictionsAPI keyDELETE/api/cogs/{id}Delete a model (tears down any warm pod first)API keyPOST/api/cogs/{id}/warmProactively cold-start the podAPI keyPOST/api/cogs/{id}/sleepScale the model to zero nowAPI keyPOST/api/cogs/{id}/predictRun a prediction asynchronously (input) — poll for the resultAPI keyGET/api/cogs/{id}/predictionsList a model’s recent predictions (up to 50)API keyGET/api/cogs/predictions/{id}Poll a prediction by id — status, output, cost, timingAPI key
POST /api/cogs body
name*stringModel display name.
image*stringContainer image, e.g. r8.im/owner/model or your own registry image.
hardwarestringA GPU machine id (gpu-t4, gpu-rtx3090, gpu-rtx4090, gpu-a40, gpu-l40s, gpu-a100, gpu-h100), or "auto"/omitted to pick the cheapest GPU that fits minVramGb.
schemaobjectOptional { inputs: [{name,type,description,default,required,choices,min,max,order}], outputKind }. Omitted schemas are introspected from the container’s /openapi.json on first warm-up.
idleSecondsintegerIdle window before scale-to-zero (default 120).
minVramGbintegerModel’s VRAM floor, used for auto hardware selection.
Ensure open audio or register any Cog
# One call: ensure Pocket TTS, queue it, and reuse it on later calls
curl -sX POST https://app.nz/api/cogs/run \
  -H "Authorization: Bearer $APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"pocket-tts","input":{"text":"Kia ora","voice":"alba","format":"wav"}}'
# -> {"created":true,"model":{"id":"..."},"prediction":{"id":"..."},
#     "lifecycle":{"scaleToZero":true,"idleSeconds":60,"status":"...","sleep":"..."}}

# Any Cog image can still be registered directly
curl -sX POST https://app.nz/api/cogs \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"fast-vfx","image":"r8.im/lee101/fast-vfx","hardware":"gpu-rtx4090"}'
# -> {"model":{"id":"cog_...","status":"idle",...}}

curl -sX POST https://app.nz/api/cogs/cog_.../predict \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input":{"video":"https://example.com/clip.mp4","num_levels":25}}'
# -> {"prediction":{"id":"pred_...","status":"starting"}}

# Poll for the result (a cold start can take a couple of minutes)
curl -s https://app.nz/api/cogs/predictions/pred_... \
  -H "Authorization: Bearer pk_live_..."

# Audio-to-audio (audex-s2s template): one spoken turn per prediction
curl -sX POST https://app.nz/api/cogs/cog_.../predict \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input":{"task":"converse","audio":"data:audio/webm;base64,...","system_prompt":"You are a cheerful pirate captain."}}'
# -> output: {"transcript":"...","response_text":"...","audio":"data:audio/mpeg;base64,..."}