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)

Finetune

Start finetuning

• Run neuralhive finetune.
• Select a task, model, and dataset.
• Review the final cost and start training.

Dataset requirements

• For slm, provide a file path.
• For other finetune tasks, provide a directory path.
• You can save a local dataset for future use.

Track progress

• Run neuralhive trainings.
• View active training names and progress.
• You can leave training running in the background.

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

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, system_prompt=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)
system_prompt	str	No	Optional system prompt for SLM models

Notes:

• If model_id is not provided, SDK uses default vlm model from your allowed models.
• system_prompt is only sent when the selected model is an slm model.

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.edit_image(image_path, prompt, export_to=None)

Parameter	Type	Required	Description
image_path	str	Yes	Local image file path
prompt	str	Yes	Text instruction for the edit
export_to	str	No	Export directory path (filename comes from response URL)

Returns:

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

client.transcribe_audio(audio_path)

Parameter	Type	Required	Description
audio_path	str	Yes	Local audio file path

Returns:

• str

client.read_text(file_path, export_to=None)

Parameter	Type	Required	Description
file_path	str	Yes	Local document file path
export_to	str	No	Export directory path for the resulting text file

Returns:

• str
• Without export_to: signed URL for the generated .txt file
• With export_to: saved local file path

client.detect_layout(file_path, export_to=None)

Parameter	Type	Required	Description
file_path	str	Yes	Local document file path
export_to	str	No	Export directory path for the resulting layout file

Returns:

• str
• Without export_to: signed URL for the generated result file
• With export_to: saved local file path

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