Infernet
Node
REST Client

REST Client

We recommend interacting with the node's REST API via the Infernet Client (opens in a new tab) Python library or CLI.

ℹ️

The following examples assume an Infernet Node is running at http://localhost:4000.

Health

Check the server's health. See HealthInfo.

from infernet_client import NodeClient
 
client = NodeClient("http://localhost:4000")
is_healthy = await client.health()
 
print(is_healthy)

Expected Output:

True

Information

Retrieve information about the node. See NodeInfo.

from infernet_client import NodeClient
 
client = NodeClient("http://localhost:4000")
info = await client.info()
 
print(info)

Expected Output:

{
  "version": "0.3.0",
  "containers": [
    {
      "id": "openai-inference-0.0.1",
      "image": "ritualnetwork/css_inference_service:latest",
      "description": "OPENAI Inference Service",
      "external": true
    }
  ],
  "pending": {
    "offchain": 5,
    "onchain": 3
  },
  "chain": {
    "enabled": true,
    "address": "0x5FbDB2315678afecb367f032d93F642f64180aa3"
  }
}

Jobs

Request

Create a new direct compute request. See JobRequest and JobResponse.

from infernet_client import NodeClient
from infernet_client.types import JobRequest
 
client = NodeClient("http://localhost:4000")
 
# Format request
request = JobRequest(
  containers=["openai-inference-0.0.1"],
  data={
    "model": "gpt-3.5-turbo-16k",
    "params": {
        "endpoint": "completion",
        "messages": [{"role": "user", "content": "how do I make pizza?"}]
    }
  }
)
 
# Send request
job_id = await client.request_job(request)
 
print(job_id)

Expected Output:

29dd2f8b-05c3-4b1c-a103-370c04c6850f

Batch Request

Create direct compute requests in batch. See JobRequest, JobResponse, and ErrorResponse.

from infernet_client import NodeClient
from infernet_client.types import JobRequest
 
client = NodeClient("http://localhost:4000")
 
# Format requests
requests = [
  JobRequest(
    containers=["openai-inference-0.0.1"],
    data={
      "model": "text-embedding-3-small",
      "params": {
        "endpoint": "embeddings",
        "input": "This string is meant to be embedded."
      }
    }
  ),
  JobRequest(
    containers=["openai-inference-0.0.1"],
    data={
      "model": "text-embedding-3-small",
      "params": {
        "endpoint": "embeddings",
        "input": "This string is meant to be embedded."
      }
    }
  ),
  JobRequest(
    containers=["non-existent-container"],
    data={
      "model": "text-embedding-3-small",
      "params": {
        "endpoint": "embeddings",
        "input": "This string is meant to be embedded."
      }
    }
  )
]
 
# Send requests
responses = await client.request_jobs(request)
 
print(responses)

Expected Output:

[
  {
    "id": "b7a7f9a7-8f80-4905-96a9-c9c7d3ef83b8"
  },
  {
    "id": "4ac0b5a5-eedb-4688-bb96-75afca891a47"
  },
  {
    "error": "Container not supported",
    "params": {
      "container": "non-existent-container"
    }
  },
]

Fetch Results

Fetch direct compute results. See JobResult.

from infernet_client import NodeClient
 
client = NodeClient("http://localhost:4000")
 
# Fetch results
results = await client.get_job_results(
  [
    "b7a7f9a7-8f80-4905-96a9-c9c7d3ef83b8",
    "4ac0b5a5-eedb-4688-bb96-75afca891a47"
  ]
)
 
print(results)

Expected Output:

[
    {
        "id": "b7a7f9a7-8f80-4905-96a9-c9c7d3ef83b8",
        "result": {
            "container": "openai-inference-0.0.1",
            "output": [
                -0.00045939715,
                0.035724517,
                0.0002739553,
                ...,
                ...,
                ...,
                0.032772407,
                0.014461349,
                0.049188532
            ]
        },
        "status": "success"
    },
    {
        "id": "4ac0b5a5-eedb-4688-bb96-75afca891a47",
        "result": {
            "container": "openai-inference-0.0.1",
            "output": [
                0.0024995692,
                -0.001929842,
                -0.007998622,
                ...,
                ...,
                ...,
                0.001959762,
                0.023656772,
                0.015548443
            ]
        },
        "status": "success"
    }
]

Sync Request

To imitate a synchronous direct compute request, you can request a job and wait until results become available. See JobRequest and JobResult.

Use get_job_result_sync, tuning the number of retries appropriately.

from infernet_client import NodeClient
from infernet_client.types import JobRequest
 
client = NodeClient("http://localhost:4000")
 
# Format request
request = JobRequest(
  containers=["openai-inference-0.0.1"],
  data={
    "model": "text-embedding-3-small",
    "params": {
      "endpoint": "embeddings",
      "input": "This string is meant to be embedded."
    }
  }
)
 
# Send request
job_id = await client.request_job(request)
 
# Wait for result, maximum of 20 retries
result = await client.get_job_result_sync(job_id, retries=20)
 
print(result)

Expected Output:

{
    "id": "b7a7f9a7-8f80-4905-96a9-c9c7d3ef83b8",
    "result": {
        "container": "openai-inference-0.0.1",
        "output": [
            -0.00045939715,
            0.035724517,
            0.0002739553,
            ...,
            ...,
            ...,
            0.032772407,
            0.014461349,
            0.049188532
        ]
    },
    "status": "success"
}

Streaming

Create a new direct compute request that streams back results synchronously. See /api/jobs/stream.

from infernet_client import NodeClient
 
client = NodeClient("http://localhost:4000")
 
# Format request
request = JobRequest(
  containers=["openai-inference-streaming-0.0.1"],
  data={
    "model": "gpt-3.5-turbo-16k",
    "params": {
      "endpoint": "completion",
      "messages": [{"role": "user", "content": "Deep Learning is "}]
    }
  }
)
 
job_id = None
 
# Iterate over streamed response
async for chunk in client.request_stream(request):
    if not job_id:
      # First chunk is the job ID
      job_id = str(chunk)
      print(f"Job ID: {job_id}")
  else:
      print(chunk.decode("utf-8"))

Expected Output:

Job ID: 449e77c9-5251-4d48-aaf0-9601aeeaf74e
a subset of machine learning, which is a broader field of artificial intelligence. It is a type of neural network that is designed to learn and improve on its own by automatically extracting features from data. Deep learning models consist of multiple layers of interconnected nodes or neurons that process and transform data in a hierarchical manner.

Deep learning is used in a variety of applications, including image and speech recognition, natural language processing, and autonomous driving. It has been particularly successful in image and speech recognition tasks, where it has achieved state-of-the-art performance in a number of benchmarks.

Get IDs

Get IDs of jobs requested by this client (by IP address.)

from infernet_client import NodeClient
 
client = NodeClient("http://localhost:4000")
 
# Get all IDs
print(await client.get_jobs())
 
# Get all completed job IDs
print(await client.get_jobs(pending=False))
 
# Get all pending job IDs
print(await client.get_jobs(pending=True))

Expected Output:

# All jobs
[
  "09b9d8bb-d752-46aa-ab95-583304827030",
  "50f098a2-daf7-47a9-9eb8-caf9b7509101",
  "29dd2f8b-05c3-4b1c-a103-370c04c6850f",
  "d77215c8-dd25-4843-89c4-788eef9ed324"
]
 
# Completed jobs
[
  "09b9d8bb-d752-46aa-ab95-583304827030",
  "50f098a2-daf7-47a9-9eb8-caf9b7509101",
  "29dd2f8b-05c3-4b1c-a103-370c04c6850f",
]
 
# Pending jobs
[
  "d77215c8-dd25-4843-89c4-788eef9ed324"
]

Delegated Subscription

Creates a new delegated subscription request. See Delegated Subscription (opens in a new tab) and DelegatedSubscriptionRequest.

from infernet_client import NodeClient
from infernet_client.chain_utils import Subscription
 
client = NodeClient("http://localhost:4000")
 
COORDINATOR_ADDRESS = "0x1FbDB2315678afecb369f032d93F642f64140aa3"
RCP_URL = "http://some-rpc-url.com"
EXPIRY = 1713376164
PRIVATE_KEY = "0xb25c7db31feed9122727bf0939dc769a96564b2ae4c4726d035b36ecf1e5b364"
 
# Container input data
input_data = {
    "model": "gpt-3.5-turbo-16k",
    "params": {
        "endpoint": "completion"
        "messages": [{"role": "user", "content": "how do I make pizza?"}]
    }
}
 
# Subscription parameters
subscription = Subscription(
    owner="0x5FbDB2315678afecb367f032d93F642f64180aa3",
    active_at=0,
    period=3,
    frequency=2,
    redundancy=2,
    max_gas_price=1000000000000,
    max_gas_limit=3000000,
    container_id="openai-inference",
    inputs=bytes(),
)
 
# Create delegated subscription
await client.request_delegated_subscription(
    subscription,
    RCP_URL,
    COORDINATOR_ADDRESS,
    EXPIRY,
    PRIVATE_KEY,
    input_data,
)

Expected Output:

# No error

Status

Manually register job ID and status with the node. See /api/status.

Warning: DO NOT USE THIS IF YOU DON'T KNOW WHAT YOU'RE DOING.

from infernet_client import NodeClient
from infernet_client.types import JobRequest
 
client = NodeClient("http://localhost:4000")
 
# Specify job parameters and request object.
job_id = d77215c8-dd25-4843-89c4-788eef9ed324
job_request = JobRequest(
  containers=["openai-inference"],
  data={}
)
 
""" Notice we are NOT running the job, just recording its status manually."""
 
# Mark a job as running
await client.record_status(
    job_id,
    "running",
    job_request,
)
 
# Mark a job as successful
await client.record_status(
    job_id,
    "success",
    job_request,
)

Expected Output:

# No error
REST APIIntroduction