Getting Started

EyePop.ai enables developers to create Pops. Pops are vision workflows that process images, videos, and livestreams into structured AI predictions: bounding boxes, confidence scores, and classificatio

Step 1 — Create an Account & Get Your API Key

1. Sign up at eyepop.ai.

2. Open the dashboard and navigate to API Keys.

3. Generate a new API key — it will look like eyp_....

4. Store it as an environment variable:

export EYEPOP_API_KEY=eyp_...

Never hardcode your API key. Load it from the environment or a .env file.

---

Step 2 — Install the SDK

Python (3.12+)

pip install eyepop

Node / React

npm install --save @eyepop.ai/eyepop

Browser (CDN)

<script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop/dist/eyepop.min.js"></script>

---

Step 3 — Connect to Your Pop

Python

The primary entry point is async_worker(). Use it with async with so the connection is automatically closed.

import asyncio
from eyepop import EyePopSdk

async def main():
    async with EyePopSdk.async_worker() as endpoint:
        # endpoint is ready — EYEPOP_API_KEY is read from the environment
        pass

asyncio.run(main())

The SDK reads EYEPOP_API_KEY and EYEPOP_URL from the environment automatically. You can also pass the key explicitly:

async with EyePopSdk.async_worker(api_key="eyp_...") as endpoint:
    ...

For scripts where async is not available (rare, one-shot image only):

from eyepop import EyePopSdk

with EyePopSdk.workerEndpoint() as endpoint:
    result = endpoint.upload("image.jpg").predict()

Node / TypeScript

import { EyePop } from '@eyepop.ai/eyepop'

const endpoint = await EyePop.workerEndpoint({ auth: { secretKey: process.env.EYEPOP_SECRET_KEY } }).connect()
try {
  // endpoint is ready
} finally {
  await endpoint.disconnect()
}

---

Step 4 — Configure a Pop

A Pop defines what models run on your endpoint. Set it after connecting:

Python

from eyepop.worker.worker_types import Pop, InferenceComponent

pop = Pop(components=[
    InferenceComponent(ability='eyepop.person:latest')
])

async with EyePopSdk.async_worker() as endpoint:
    await endpoint.set_pop(pop)
    # now run predictions

Node / TypeScript

await endpoint.changePop({
    components: [{ ability: 'eyepop.person:latest' }]
})

---

Step 5 — Run Your First Prediction

Upload a local file

Python

async with EyePopSdk.async_worker() as endpoint:
    await endpoint.set_pop(pop)
    job = await endpoint.upload("image.jpg")
    result = await job.predict()
    print(result)

Node

const results = await endpoint.process({ file: 'image.jpg' })
for await (const result of results) {
    console.log(result)
}

Load from a URL or RTSP stream

Python

job = await endpoint.load_from("https://example.com/photo.jpg")
result = await job.predict()

# or an RTSP camera stream
job = await endpoint.load_from("rtsp://camera-ip/stream")
while result := await job.predict():
    print(result)

Node

const results = await endpoint.process({ url: 'https://example.com/video.mp4' })
for await (const result of results) {
    console.log(result)
}

---

Step 6 — Understand the Output

Predictions return structured JSON. Example response:

{
  "source_width": 1920,
  "source_height": 1080,
  "seconds": 0.083,
  "objects": [
    {
      "classLabel": "person",
      "confidence": 0.95,
      "x": 100,
      "y": 50,
      "width": 80,
      "height": 200
    }
  ]
}

Result key	Used by
objects	Detection abilities (eyepop.person:latest, eyepop.vehicle:latest, etc.)
classes	Classification abilities
texts	VLM / describe abilities and OCR

---

Step 7 — Process Video (Async Frame Loop)

For video files or live streams, iterate frame-by-frame:

async with EyePopSdk.async_worker() as endpoint:
    await endpoint.set_pop(pop)
    job = await endpoint.upload("video.mp4")
    while result := await job.predict():
        print(result)   # one result per frame

To process at a lower frame rate (e.g., 1 fps):

job = await endpoint.upload("video.mp4", target_fps=1)

---

Step 8 — Batch Processing

Process multiple files concurrently using asyncio.gather:

import asyncio
from eyepop import EyePopSdk
from eyepop.worker.worker_types import Pop, InferenceComponent

FILES = ["img1.jpg", "img2.jpg", "img3.jpg"]

async def process(endpoint, path):
    job = await endpoint.upload(path)
    return await job.predict()

async def main():
    pop = Pop(components=[InferenceComponent(ability='eyepop.person:latest')])
    async with EyePopSdk.async_worker() as endpoint:
        await endpoint.set_pop(pop)
        results = await asyncio.gather(*[process(endpoint, f) for f in FILES])
    for r in results:
        print(r)

asyncio.run(main())

---

Step 9 — Visualization

from eyepop import EyePopSdk
from PIL import Image
import matplotlib.pyplot as plt

with Image.open("image.jpg") as image:
    plt.imshow(image)

plot = EyePopSdk.plot(plt.gca())
plot.prediction(result)
plt.show()

Node / Canvas (browser or Node)

import Render2d from '@eyepop.ai/eyepop-render-2d'

const renderer = Render2d.renderer(context, [
    Render2d.renderBox({ showClass: true, showConfidence: true })
])
renderer.draw(result)

---

Step 10 — Live Browser Streams (Node / Browser only)

Connect a browser MediaStream directly to an EyePop endpoint:

const stream = await navigator.mediaDevices.getUserMedia({ video: true })
const ingressId = await endpoint.liveIngress(stream)
const results = await endpoint.process({ ingressId })
for await (const result of results) {
    console.log(result)
}

liveIngress is a browser/Node API and takes a MediaStream. It is not available in the Python SDK.

---

Step 11 — Authentication Options

Method	Use case
api_key= / EYEPOP_API_KEY env var	Server-side — standard eyp_... key for transient cloud inference
secret_key=	Server-side — long encoded key for named pops
Session token	Browser apps — generate a short-lived token server-side and pass it to the client
OAuth2	Development / dashboard login only

Python — standard (transient pop)

# Preferred: let the SDK read EYEPOP_API_KEY from the environment
async with EyePopSdk.async_worker() as endpoint: ...

# Or pass explicitly
async with EyePopSdk.async_worker(api_key="eyp_...") as endpoint: ...

Python — named pop with secret key

async with EyePopSdk.async_worker(secret_key="<long-encoded-key>") as endpoint: ...

api_key and secret_key are not interchangeable. Passing an eyp_... key as secret_key raises a ValueError at runtime.

Node — generate a session token for browser clients

// Server side
const sessionToken = await endpoint.session()

// Browser client
const clientEndpoint = await EyePop.workerEndpoint({ auth: { session: sessionToken } }).connect()

---

Step 12 — Deploy On-Premise (Optional)

EyePop supports on-premise deployment for IP camera workflows. Run eyepop-instance locally to process RTSP streams with cloud inference offload and a local dashboard.

Use is_local_mode=True in the SDK to connect to a local instance instead of the cloud:

async with EyePopSdk.async_worker(is_local_mode=True) as endpoint:
    await endpoint.set_pop(pop)
    job = await endpoint.upload("image.jpg")
    result = await job.predict()

---

Tuning Options

Option	Python	Node	Effect
Disable auto-start	auto_start=False	autoStart: false	Don't start a worker on connect
Preserve pending jobs	stop_jobs=False	stopJobs: false	Keep queued jobs when disconnecting

---

Resources

• Dashboard

• Python SDK

• Node SDK

• Example projects

• Full documentation