neuralhive 1.1.1

NeuralHive Python SDK for model access and inference

NeuralHive SDK

Python SDK client for NeuralHive model access.

Installation

pip install neuralhive

Authentication Setup

Option 1: Configure once (recommended)

neuralhive configure --api-key nh_live_your_api_key

Then use SDK without passing key in code.

Option 2: Environment variable

export NEURALHIVE_API_KEY="nh_live_your_api_key"

Option 3: Pass key directly in code

client = Client("nh_live_your_api_key")

Quick Start

from neuralhive import Client

client = Client()
models = client.list_models()
print(models)

Usage

1. Get model details

model = client.get_model("your_model_id")
print(model)

2. Run model inference

from neuralhive import Client

client = Client()

result = client.detect(
    image_path="/absolute/path/to/image.jpg",
)

For all other methods, see API Reference below.

API Reference

Client(api_key: str | None = None)

Parameter	Type	Required	Description
api_key	str	No	Your NeuralHive API key

Returns:

• Client instance

Notes:

• Authentication is validated automatically on first API call.
• Production recommendation: avoid hardcoded API keys in source code.

client.list_models()

Parameters:

• None

Returns:

• list[dict] containing allowed models for this API key

client.get_model(model_id)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier

Returns:

• dict with model details

client.detect(image_path, model_id=None, prompt=None, export_to=None)

Parameter	Type	Required	Description
image_path	str	Yes	Local image file path
model_id	str	No	Target model identifier
prompt	str	No	Optional prompt (required for SAM-like IDs)
export_to	str	No	Export directory path for box-rendered image

Notes:

• If model_id is not provided, SDK uses default object_detection model from your allowed models.

Returns:

• dict

client.segment(image_path, model_id=None, prompt=None, export_to=None)

Parameter	Type	Required	Description
image_path	str	Yes	Local image file path
model_id	str	No	Target model identifier
prompt	str	No	Optional prompt (required for SAM-like IDs)
export_to	str	No	Export directory path for mask-rendered image

Returns:

• dict

Notes:

• If model_id is not provided, SDK uses default instance_segmentation model from your allowed models.

client.detect_and_segment(image_path, prompt, export_to=None)

Parameter	Type	Required	Description
image_path	str	Yes	Local image file path
prompt	str	Yes	Segmentation prompt
export_to	str	No	Export directory path for mask+box-rendered image

Notes:

• Uses SAM3 / prompt-based segmentation models.

Returns:

• dict

client.recognize(image_path)

Parameter	Type	Required	Description
image_path	str	Yes	Local image file path

Returns:

• list[list[float]] (face embeddings per detected face)

client.reidentify(image_path, model_id=None)

Parameter	Type	Required	Description
image_path	str	Yes	Local image file path
model_id	str	No	Target model identifier

Returns:

• dict

client.estimate_pose(image_path, export_to=None)

Parameter	Type	Required	Description
image_path	str	Yes	Local image file path
export_to	str	No	Export directory path for pose-rendered image

Returns:

• dict with:
• keypoints: list[object]
• scores: list[object]
• saved_path: str | None

client.embed(text=None, image_path=None, model_id=None)

Parameter	Type	Required	Description
text	str	No	Text input
image_path	str	No	Local image file path
model_id	str	No	Target model identifier

Notes:

• Exactly one input is required: text or image_path
• If model_id is not provided, SDK uses the default clip model from your allowed models.

Returns:

• list[float] or list[list[float]]

client.generate_text(prompt, model_id=None, image_paths=None, video_paths=None)

Parameter	Type	Required	Description
prompt	str	Yes	Text prompt
model_id	str	No	Target model identifier
image_paths	str or list[str]	No	Local image file path(s)
video_paths	str or list[str]	No	Local video path(s) or public URL(s)

Notes:

• If model_id is not provided, SDK uses default vlm model from your allowed models.

Returns:

• str

client.analyze(text=None, image_paths=None, video_paths=None)

Parameter	Type	Required	Description
text	str	No	Text input
image_paths	str or list[str]	No	Local image file path(s)
video_paths	str or list[str]	No	Local video path(s) or public URL(s)

Notes:

• At least one input is required: text or image_paths or video_paths

Returns:

• str

client.generate_image(prompt, export_to=None)

Parameter	Type	Required	Description
prompt	str	Yes	Text prompt
export_to	str	No	Export directory path (filename comes from response URL)

Returns:

• dict with:
• download_url: str
• saved_path: str | None

client.generate_3d(image_path, export_to=None)

Parameter	Type	Required	Description
image_path	str	Yes	Local image file path
export_to	str	No	Export directory path (filename comes from response URL)

Returns:

• dict with:
• download_url: str
• saved_path: str | None