NetMind Python API library

The NetMind Python API Library is the official Python client for NetMind's API platform, providing a convenient way for interacting with the REST APIs and enables easy integrations with Python 3.10+ applications with easy to use synchronous and asynchronous clients.

📚 Table of Contents

• Installation
  • Setting up API Key
    • Setting environment variable
    • Using the client
• Usage – Python Client
  • Chat Completions
    • Streaming
    • Async usage
  • Embeddings
    • Async usage
  • Files
    • Async usage
  • ParsePro
    • Async Task usage
    • ParsePro Async usage
  • Code interpreter
    • Simple Usage
    • File Usage
    • Generate Picture
• Usage – CLI

Installation

To install NetMind Python Library from PyPI, simply run:

pip install --upgrade netmind

Setting up API Key

You will need to create an account with NetMind.ai to obtain a NetMind API Key.

Once logged in to the NetMind Playground, you can find available API keys in Dashboard.

Setting environment variable

export NETMIND_API_KEY=<your_netmind_api_key>

Using the client

from netmind import NetMind


client = NetMind(api_key="your_netmind_api_key")

This repo contains both a Python Library and a CLI. We'll demonstrate how to use both below.

Usage – Python Client

Chat Completions

👉 Supports plain text and multi-modal messages. Use content array with type: "text" and type: "image_url" for image input.

from netmind import NetMind


client = NetMind()


# Simple text message
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "Act like you are a helpful assistant."},
        {"role": "user", "content": "Hi there!"},
    ],
    max_tokens = 512
)
print(response.choices[0].message.content)

# Multi-modal message with text and image
response = client.chat.completions.create(
    model="doubao/Doubao-1.5-vision-pro",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's in this image?"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/yosemite.png"
                }
            }
        ]
    }]
)
print(response.choices[0].message.content)

The chat completions API supports three types of content:

• Plain text messages using the content field directly
• Multi-modal messages with images using type: "image_url"

When using multi-modal content, the content field becomes an array of content objects, each with its own type and corresponding data.

Streaming

👉 Use stream=True for incremental, real-time responses.

from netmind import NetMind


client = NetMind()
stream = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=[
        {"role": "system", "content": "Act like you are a helpful assistant."},
        {"role": "user", "content": "Hi there!"},
    ],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Async usage

👉 Use the AsyncNetMind class for asynchronous environments. All async methods require await and work well with frameworks like FastAPI.

import asyncio
from netmind import AsyncNetMind


async_client = AsyncNetMind()


async def async_chat_completion():
    response = await async_client.chat.completions.create(
        model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
        messages=[
            {"role": "system", "content": "Act like you are a helpful assistant."},
            {"role": "user", "content": "Hi there!"},
        ]
    )
    print(response.choices[0].message.content)


asyncio.run(async_chat_completion())

Embeddings

👉 Supports list inputs and returns embeddings for each entry.

from netmind import NetMind

client = NetMind()


response = client.embeddings.create(
    model="nvidia/NV-Embed-v2",
    input=["Hello world", "NetMind is awesome!"]
)
print(len(response.data[0].embedding))

Async usage

import asyncio
from netmind import AsyncNetMind


async_client = AsyncNetMind()


async def async_embeddings():
    response = await async_client.embeddings.create(
        model="nvidia/NV-Embed-v2",
        input=["Hello world", "NetMind is awesome!"]
    )
    print(len(response.data[0].embedding))
asyncio.run(async_embeddings())

Files

👉 Required for async file-based operations like aparse(). Upload local files to get a downloadable URL via client.files.create().

from netmind import NetMind
from netmind.types.files import FilePurpose


client = NetMind()


# Upload a file
file_response = client.files.create(
    file="path/to/your/file.jsonl",
    purpose=FilePurpose.inference
)
print(f"File uploaded with ID: {file_response.id}")

# List files
files = client.files.list()
print("files found:", len(files))
print("files id:", files[0].id)


file_id = "your_file_id_here"
# Retrieve a file
file = client.files.retrieve(file_id)  
print(file)

# Retrieve download url for a file
download_url = client.files.retrieve_url(file_id)
print("Download URL:", download_url.presigned_url)


# Delete a file
client.files.delete(file_id)

Async usage

import asyncio
from netmind import AsyncNetMind
from netmind.types.files import FilePurpose


async_client = AsyncNetMind()


async def async_file_operations():
    # Upload a file
    file_response = await async_client.files.create(
        file="path/to/your/file.jsonl",
        purpose=FilePurpose.fine_tune
    )
    print(f"File uploaded with ID: {file_response.id}")

    # List files
    files = await async_client.files.list()
    print("files found:", len(files.data))

    file_id = "your_file_id_here"
    # Retrieve a file
    file = await async_client.files.retrieve(file_id)  
    print(file)

    # Retrieve download url for a file
    download_url = await async_client.files.retrieve_url(file_id)
    print("Download URL:", download_url.presigned_url)

    # Delete a file
    await async_client.files.delete(file_id)

asyncio.run(async_file_operations())

ParsePro

✅ Sync method parse() supports both local files and URLs.

from netmind import NetMind


client = NetMind()

result = client.parse_pro.parse(
    source='https://raw.githubusercontent.com/protagolabs/netmind-python/main/demo/test.pdf',
    format='json' # or 'markdown'
)
print(result)

result = client.parse_pro.parse(
    source='/path/to/test.pdf',
    format='json' # or 'markdown'
)
print(result)

Async Task usage

⚠️ Async parsing requires a public URL. Local files must be uploaded first. Use client.files.create() to generate a usable URL.

from netmind import NetMind
import time


client = NetMind()

# Step 1: create async task
task = client.parse_pro.aparse(
    source='https://raw.githubusercontent.com/protagolabs/netmind-python/main/demo/test.pdf',
    format='json' # or "markdown"
)

print("Task ID:", task.task_id, "| Status:", task.status)

# Step 2: poll until the task is finished
for _ in range(60): # up to ~3 minutes
    time.sleep(3)
    result = client.parse_pro.aresult(task.task_id)
    print("Status:", result.status)

    if result.status in ["SUCCESS", "FAILURE"]:
        print(result.data)   # parsed content
        break

ParsePro Async usage

from netmind import AsyncNetMind
import asyncio
import time


client = AsyncNetMind()


async def main():
    task = await client.parse_pro.aparse(
        source='https://raw.githubusercontent.com/protagolabs/netmind-python/main/demo/test.pdf',
        format='markdown' # or "json"
    )

    print("Task ID:", task.task_id, "| Status:", task.status)

    # Step 2: poll until the task is finished
    for _ in range(60): # up to ~3 minutes
        time.sleep(3)
        result = await client.parse_pro.aresult(task.task_id)
        print("Status:", result.status)

        if result.status in ["SUCCESS", "FAILURE"]:
            print("Final status:", result.status)
            print(result.data)   # parsed content
            break


asyncio.run(main())

ℹ️ Notes

• ✅ parse() (sync) supports both URLs and local files.
• ⚠️ aparse() and all async parsing require a public URL – local files must be uploaded first.
• ✅ Use client.files.create() to upload files and get a downloadable URL.
• 🧠 Async clients (AsyncNetMind) are ideal for integration into event loops or async workflows.
• 🎯 Multi-modal chat input must use structured content arrays.

Code interpreter

simple usage

from netmind import NetMind
from netmind.types.code_interpreter import CodeInterpreterCodeRequest, CodeInterpreterCodeFile


client = NetMind()

SAMPLE_CODE_REQUEST = CodeInterpreterCodeRequest(
    language="python",
    files=[
        CodeInterpreterCodeFile(
            name="main.py",
            content="print('Hello, World!')\nprint(2 + 2)\nresult = 5 * 3\nprint(f'Result: {result}')"
        )
    ]
)
run_response = client.code_interpreter.run(SAMPLE_CODE_REQUEST)
print(run_response.run.stdout)

file usage

from netmind import NetMind
from netmind.types.code_interpreter import CodeInterpreterCodeRequest, CodeInterpreterCodeFile

client = NetMind()

upload_response = client.files.create(purpose="code-interpreter", file='temp.json')

SAMPLE_CODE_REQUEST = CodeInterpreterCodeRequest(
    language="python",
    files=[
        CodeInterpreterCodeFile(
            name="main.py",
            content="import json\nimport sys\n\ndef main():\n    filename = \"temp.json\"\n    try:\n        with open(filename, \"r\", encoding=\"utf-8\") as f:\n            data = json.load(f)  # PARSE JSON\n    except FileNotFoundError:\n        print(f\"error：'{filename}'\", file=sys.stderr)\n        sys.exit(1)\n    except json.JSONDecodeError as e:\n        print(f\"error：{e}\", file=sys.stderr)\n        sys.exit(1)\n\n    # original Python object\n    print(\"READ:\")\n    print(data)\n\n    #Print JSON 文本\n    print(\"\\nJSON Content：\")\n    pretty = json.dumps(data, ensure_ascii=False, indent=2)\n    print(pretty)\n\nif __name__ == \"__main__\":\n    main()"
        )
    ],
    file_id_usage=[upload_response.id]
)
run_response = client.code_interpreter.run(SAMPLE_CODE_REQUEST)
print(run_response.run.stdout)

generate picture

from netmind import NetMind
from netmind.types.code_interpreter import CodeInterpreterCodeRequest, CodeInterpreterCodeFile

client = NetMind()

SAMPLE_CODE_REQUEST = CodeInterpreterCodeRequest(
    language="python",
    files=[
        CodeInterpreterCodeFile(
            name="main.py",
            content="from PIL import Image, ImageDraw\n\n# Create RGB Picture，200x100 \nimg = Image.new('RGB', (200, 100), color = 'white')\nd = ImageDraw.Draw(img)\nd.text((10, 40), 'Hello, PNG!', fill=(0, 0, 0))\n\n# save as PNG\nimg.save('output.png')"
        )
    ]
)
run_response = client.code_interpreter.run(SAMPLE_CODE_REQUEST)

download_url = client.files.retrieve_url(run_response.run.data.id)

Usage – CLI

coming soon