neuralhive 1.1.0

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. List models

from neuralhive import Client

client = Client("nh_live_your_api_key")
models = client.list_models()

2. Get model details

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

3. Run model inference

from neuralhive import Client

client = Client("nh_live_your_api_key")

result = client.detect(
    model_id="your_object_detection_model_id",
    image="<base64_image>",
)

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(model_id, image, prompt=None)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
image	str	Yes	Base64 image input
prompt	str	No	Optional prompt (required for SAM-like IDs)

Returns:

• dict

client.segment(model_id, image, prompt=None)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
image	str	Yes	Base64 image input
prompt	str	No	Optional prompt (required for SAM-like IDs)

Returns:

• dict

client.recognize(model_id, image)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
image	str	Yes	Base64 image input

Returns:

• list[float] (face embeddings)

client.reidentify(model_id, image)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
image	str	Yes	Base64 image input

Returns:

• dict

client.estimate_pose(model_id, image)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
image	str	Yes	Base64 image input

Returns:

• dict

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

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
text	str	No	Text input
image	str	No	Base64 image input

Notes:

• Exactly one input is required: text or image

Returns:

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

client.generate_text(model_id, prompt, image=None, images=None, videos=None)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
prompt	str	Yes	Text prompt
image	str	No	Single base64 image
images	str or list[str]	No	Base64 image(s)
videos	str or list[str]	No	Video URL(s) or base64 video input(s)

Returns:

• str

client.analyze(model_id, text=None, images=None, videos=None)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
text	str	No	Text input
images	str or list[str]	No	Base64 image(s)
videos	str or list[str]	No	Video URL(s) or base64 video input(s)

Notes:

• At least one input is required: text or images or videos

Returns:

• str

client.generate_image(model_id, prompt)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
prompt	str	Yes	Text prompt

Returns:

• str (generated image URL, empty string if unavailable)

client.generate_3d(model_id, image)

Parameter	Type	Required	Description
model_id	str	Yes	Target model identifier
image	str	Yes	Base64 image input

Returns:

• str (3D asset URL, empty string if unavailable)

Input Validation

• model_id is required for all inference methods.
• task_type is never required from user.
• image and images must be base64-encoded strings when provided.
• Unsupported fields for selected model are rejected before request dispatch.
• Missing required fields for selected model are rejected before request dispatch.

Contract

Frozen contract file is included in repository.