Bring your own model

Custom models are currently available in early access. Reach out to your Cyberwave contact to enable it for your workspace.

Concepts

A custom model is an AI model you register yourself, instead of picking one from the catalog. There are two kinds:

custom-api

Your model already runs somewhere — your own inference server, a HuggingFace Inference Endpoint, a colleague’s project. Cyberwave calls it over HTTP whenever the model is used.

custom-hosted

You give Cyberwave a Python function; Cyberwave runs it for you on demand. No servers to keep online yourself.

Both kinds are ordinary MLModel rows once created — they show up in the model catalog, can be selected in a workflow’s Call Model node, and run through the same POST /mlmodels/{uuid}/run endpoint and Playground as any built-in model. Custom models are always scoped to private or workspace visibility (never made public to other workspaces).

Describing inputs and outputs

Every custom model declares its inputs and outputs with metadata.io_schema — a list of named, typed ports:

{
  "io_schema": {
    "inputs": [
      { "name": "prompt", "type": "text", "required": false },
      { "name": "frame", "type": "image", "required": true }
    ],
    "outputs": [{ "name": "detections", "type": "json" }]
  }
}

Supported types: text, image, audio, video, json, number, boolean, array. video is a reference to a stored recording (a whole clip), not a single live frame — see Passing a recording as input.

Custom port contracts can also declare data meaning, such as units, coordinate frame and joint order. Two array outputs are not interchangeable merely because their sizes match. Review the mapping when replacing a model; reload its latest configuration if a contract update reports a conflict. Existing untyped models retain their current behavior.

Only upload or point at code and endpoints you trust. Custom models run without additional sandboxing today — treat them the same way you’d treat any other code you run on your own infrastructure.

Upload a model hosted behind your API

Use this when the model already runs somewhere reachable over HTTPS.

Create the model with model_provider_name: "custom-api" and your endpoint configuration in metadata.

from cyberwave import Cyberwave

cw = Cyberwave(api_key="your_api_key")

model = cw.api.src_app_api_mlmodels_create_mlmodel(ml_model_create_schema={
    "name": "Warehouse Defect Classifier",
    "description": "Calls our own defect-detection API",
    "model_external_id": "defect-classifier-v1",
    "model_provider_name": "custom-api",
    "visibility": "private",
    "can_take_image_as_input": True,
    "output_format": "json",
    "metadata": {
        "endpoint_url": "https://api.example.com/v1/classify",
        "http_method": "POST",
        "payload_template": {
            "model": "{model_id}",
            "image": "{image_url}"
        },
        "response_key": "output",
        "timeout_seconds": 30,
        "max_retries": 1,
        "io_schema": {
            "inputs": [{ "name": "frame", "type": "image", "required": True }],
            "outputs": [{ "name": "defects", "type": "json" }]
        }
    }
})
print(model.uuid)

payload_template values may use the placeholders {prompt}, {model_id}, and (for video inputs) {video_url} — Cyberwave substitutes them into the JSON body it sends to endpoint_url. response_key names the top-level field in your endpoint’s JSON response that holds the result.timeout_seconds defaults to 120 and is a budget for the whole call, retries included — max_retries never extends it. Values outside the allowed range are clamped; unparseable values fall back to the default.A few metadata keys are reserved for the Cyberwave platform and are rejected on create and update: cloud_node_profile_slug, cloud_node_result_type, fallback_provider, and fallback_model_id.

Add authentication (if your endpoint needs it)

Credentials are write-only: once set, Cyberwave never returns the secret value again — only whether one is configured.

curl -X POST \
  "$CYBERWAVE_BASE_URL/api/v1/mlmodels/<model-uuid>/credential" \
  -H "Authorization: Bearer $CYBERWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_type": "bearer",
    "secret": "sk-your-endpoint-token"
  }'

auth_type is one of none, bearer, api_key_header (also set header_name, e.g. "X-API-Key"), or basic. Remove a credential with DELETE .../credential.

Test it

Run one real call against your endpoint to confirm the config:

curl -X POST \
  "$CYBERWAVE_BASE_URL/api/v1/mlmodels/<model-uuid>/test-call" \
  -H "Authorization: Bearer $CYBERWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/sample.jpg"}'

This is a real inference against your endpoint, so it consumes credits like any other run. It requires metadata.endpoint_url to be set.

Use it

The model now behaves like any catalog model — run it directly, from the Playground, or from a workflow’s Call Model node.

result = cw.models.run(model.uuid, image_url="https://example.com/frame.jpg")

Upload a model and let Cyberwave host it

Use this when you don’t want to run your own server — give Cyberwave a Python function and (optionally) a weights file, and Cyberwave runs it on demand. Your code must define one function:

def run(inputs: dict, artifacts_dir: str | None) -> dict:
    # inputs matches your declared io_schema.inputs, e.g. {"prompt": "...", "frame": "..."}
    # artifacts_dir is a local path to your downloaded weights, or None if you didn't upload any
    ...
    return {"detections": [...]}   # matches your declared io_schema.outputs

The base runtime ships with torch, onnxruntime, ultralytics, opencv, numpy, pillow, and transformers pre-installed — import them directly from run(). Installing extra packages at run time isn’t supported yet.

All custom-hosted models run on GPU-backed compute today, even a small model that would run fine on CPU. You can set metadata.device to "cpu" or "gpu" now to declare which one your model actually needs — it’s validated and saved, but not yet used to choose your compute: every workload still runs on GPU regardless of this value. Setting it today costs you nothing and means no changes are needed on your side once CPU-tier compute ships.

model = cw.api.src_app_api_mlmodels_create_mlmodel(ml_model_create_schema={
    "name": "My Detector",
    "description": "Custom ONNX detector, hosted by Cyberwave",
    "model_external_id": "my-detector-v1",
    "model_provider_name": "custom-hosted",
    "visibility": "private",
    "can_take_image_as_input": True,
    "output_format": "json",
    "metadata": {
        "code": open("run.py").read(),
        "device": "cpu",
        "io_schema": {
            "inputs": [{ "name": "frame", "type": "image", "required": True }],
            "outputs": [{ "name": "detections", "type": "json" }]
        }
    }
})

Only inline code (metadata.code, shown above) is supported today — uploading code as a separate file isn’t wired up yet.

metadata.device is optional ("cpu" or "gpu") — see the note above. It’s only valid on custom-hosted models; setting it on custom-api is rejected, since your own endpoint decides its own compute.

Upload weights (optional)

If your run() function needs a checkpoint, upload it as a tar archive in two steps: request a signed upload URL, then confirm the upload.

# 1. Request a signed URL
curl -X POST \
  "$CYBERWAVE_BASE_URL/api/v1/mlmodels/<model-uuid>/artifacts/upload-urls" \
  -H "Authorization: Bearer $CYBERWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"path": "checkpoint.tar"}]}'

# 2. PUT your file to the returned upload_url, then confirm:
curl -X POST \
  "$CYBERWAVE_BASE_URL/api/v1/mlmodels/<model-uuid>/artifacts/complete" \
  -H "Authorization: Bearer $CYBERWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"path": "checkpoint.tar"}], "primary_path": "checkpoint.tar"}'

Your run() function receives the extracted contents’ directory as artifacts_dir.

Run it

Same as any other model — direct call, Playground, or a workflow’s Call Model node. The first run after registering may take longer while capacity is provisioned.

result = cw.models.run(model.uuid, image_url="https://example.com/frame.jpg")

Passing a recording as input

A model that analyzes a whole recorded clip (rather than a single live frame) declares a video-typed input in its io_schema, and the caller passes the recording’s UUID:

result = cw.api.run_mlmodel(
    model.uuid,
    recording_uuid="<recording-uuid>",   # from GET /twins/{uuid}/recordings
)

Cyberwave resolves recording_uuid into a temporary signed URL for the underlying video file before calling your endpoint or run() function. Whole-clip calls typically take longer than a single-frame call — timeouts are extended automatically when a model declares a video input.

Endpoint reference

Method	Path	Purpose
`POST`	`/api/v1/mlmodels`	Register a `custom-api` or `custom-hosted` model.
`POST`	`/api/v1/mlmodels/{uuid}/credential`	Set (or replace) auth credentials.
`DELETE`	`/api/v1/mlmodels/{uuid}/credential`	Remove stored credentials.
`POST`	`/api/v1/mlmodels/{uuid}/test-call`	Run one validation call against your endpoint.
`POST`	`/api/v1/mlmodels/{uuid}/artifacts/upload-urls`	Request signed URLs to upload weights.
`POST`	`/api/v1/mlmodels/{uuid}/artifacts/complete`	Confirm an uploaded artifact.
`POST`	`/api/v1/mlmodels/{uuid}/run`	Run the model.

Where to go next

Model catalog

Model visibility, capabilities, and the catalog in general.

Model playground

Try any model — including your own — from an interactive UI.

Model Catalog API

Full request/response reference for the model catalog endpoints.

Get started

AI agents

AI models

Control

Learn

Run on edge or cloud

Platform

For integrators

Help

Concepts

custom-api

custom-hosted

Describing inputs and outputs

Upload a model hosted behind your API

Upload a model and let Cyberwave host it

Passing a recording as input

Endpoint reference

Where to go next

Model catalog

Model playground

Model Catalog API

​Concepts

custom-api

custom-hosted

​Describing inputs and outputs

​Upload a model hosted behind your API

​Upload a model and let Cyberwave host it

​Passing a recording as input

​Endpoint reference

​Where to go next

Model catalog

Model playground

Model Catalog API

Concepts

Describing inputs and outputs

Upload a model hosted behind your API

Upload a model and let Cyberwave host it

Passing a recording as input

Endpoint reference

Where to go next