Getting Started

Creating your first Pop and running a demo.

How does EyePop.ai work?

You will create endpoints that use a cloud or edge based AI worker server that streamlines your detection tasks. We call these endpoints a “Pop”. Whether you're looking to post images, videos, or even connect through live webrtc, EyePop.ai offers the flexibility and efficiency to suit your requirements.

Build your first "Pop" Endpoint

EyePop.ai Quickstart Guide

This guide walks you from zero → first working visual intelligence task using EyePop.ai.

---

What You're Building

You'll create your first Pop — a configured worker endpoint that turns images, video, or livestreams into structured predictions (bounding boxes, classes, confidence scores, and more).

Example use cases:

• Classify an image

• Detect objects or events in video

• Process live RTSP / RTMP streams

• Identify behavior (e.g. "person entering")

---

Step 1 — Create an Account & Get Credentials

1. Sign up at https://eyepop.ai

2. In your profile, generate a Secret API Key and copy it

• EYEPOP_API_KEY — your secret key, used to authenticate

Store them as environment variables (recommended) or pass them explicitly to the SDK.

export EYEPOP_API_KEY="your-api-key"

---

Step 2 — Install the SDK

Python (3.8+)

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

The SDK authenticates with your API key and loads the worker configuration for the Pop identified by EYEPOP_POP_ID.

Python

import os
from eyepop import EyePopSdk

endpoint = EyePopSdk.workerEndpoint(
    secret_key=os.environ.get('EYEPOP_API_KEY'),  # default; can be omitted
)

endpoint.connect()
endpoint.set_pop(<POP_DEFINITION>)
# do work ...
endpoint.disconnect()

Or, more idiomatically, use a context manager so resources are cleaned up automatically:

from eyepop import EyePopSdk

with EyePopSdk.workerEndpoint() as endpoint:
    endpoint.set_pop(<POP_DEFINITION>)
    # do work ...
    pass

Node / TypeScript

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

(async () => {
    const endpoint = await EyePop.workerEndpoint({
        auth: { secretKey: process.env['EYEPOP_API_KEY'] },
    }).connect()
    await client.changePop(<POP_DEFINITION>);

    // do work ...
    await endpoint.disconnect()
})()

Shorter form (reads env vars automatically):

const endpoint = await EyePop.workerEndpoint().connect()

---

Step 4 — Run Your First Prediction

Python — upload a single image

from eyepop import EyePopSdk

def upload_photo(file_path: str):
    with EyePopSdk.workerEndpoint() as endpoint:
        result = endpoint.upload(file_path).predict()
        print(result)

upload_photo('examples/example.jpg')

• endpoint.upload(path) queues the file for processing.

• predict() blocks until the first prediction is available and returns it as a dict.

• For videos or image containers (GIF, etc.), call predict() in a loop — one result per frame — until it returns None.

Python — load from a URL (HTTP, RTSP, or RTMP)

from eyepop import EyePopSdk

with EyePopSdk.workerEndpoint() as endpoint:
    result = endpoint.load_from(
        'https://farm2.staticflickr.com/1080/1301049949_532835a8b5_z.jpg'
    ).predict()
    print(result)

Node — upload a single image

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

(async () => {
    const endpoint = await EyePop.workerEndpoint().connect()
    try {
        const results = await endpoint.process({ file: 'examples/example.jpg' })
        for await (const result of results) {
            console.log(result)
        }
    } finally {
        await endpoint.disconnect()
    }
})()

• endpoint.process({...}) accepts a file path, a url, or a readable stream with a mimeType.

• Results are streamed as an AsyncIterable<Prediction> — iterate with for await.

Node — load from a URL

const results = await endpoint.process({
    url: 'https://farm2.staticflickr.com/1080/1301049949_532835a8b5_z.jpg'
})
for await (const result of results) {
    console.log(result)
}

---

Step 5 — Understand the Output

EyePop returns structured JSON, not raw model text. A typical prediction includes the source dimensions and a list of detected objects with bounding boxes, classes, and confidence scores.

Example (shape will vary by Pop configuration):

{
  "source_width": 1280,
  "source_height": 720,
  "seconds": 0.0,
  "objects": [
    {
      "classLabel": "person",
      "confidence": 0.97,
      "x": 420, "y": 180, "width": 160, "height": 340
    }
  ]
}

This is easy to plug directly into:

• alerts

• workflows

• dashboards

• automation systems

---

Step 6 — Process Batches Efficiently

Python — synchronous batch

Queue all jobs first, then collect results. This avoids paying the HTTP roundtrip per image.

from eyepop import EyePopSdk

def upload_photos(file_paths: list[str]):
    with EyePopSdk.workerEndpoint() as endpoint:
        jobs = [endpoint.upload(p) for p in file_paths]
        for job in jobs:
            print(job.predict())

upload_photos(['examples/example.jpg'] * 100)

Python — asynchronous batch (high throughput)

For very large batches, use the async variant with an on_ready callback so results are processed as soon as they land.

import asyncio
from eyepop import EyePopSdk, Job

async def async_upload_photos(file_paths: list[str]):
    async def on_ready(job: Job):
        print(await job.predict())

    async with EyePopSdk.workerEndpoint(is_async=True) as endpoint:
        for file_path in file_paths:
            await endpoint.upload(file_path, on_ready)

asyncio.run(async_upload_photos(['examples/example.jpg'] * 100000))

Node — parallel processing

Don't await each call; use .then() so uploads run in parallel (up to 5 HTTP connections per endpoint).

for (let i = 0; i < 100; i++) {
    endpoint.process({ path: 'examples/example.jpg' }).then(async (results) => {
        for await (const result of results) {
            console.log(`result for #${i}`, result)
        }
    })
}

---

Step 7 — Process Video

The same Pop handles video via upload or public URL — HTTP, RTSP, or RTMP.

Python

from eyepop import EyePopSdk

with EyePopSdk.workerEndpoint() as endpoint:
    job = endpoint.load_from(
        'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4'
    )
    while result := job.predict():
        print(result)

Node

const results = await endpoint.process({
    url: 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4'
})
for await (const result of results) {
    console.log(result)
}

Canceling a job mid-stream

while result := job.predict():
    print(result)
    if result['seconds'] >= 10.0:
        job.cancel()

for await (const result of results) {
    if (result['seconds'] >= 10.0) {
        results.cancel()
    }
}

---

Step 8 — Process a Live Stream (Browser)

Connect EyePop to a real-time MediaStream (e.g. from getUserMedia) via liveIngress.

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

const setupLiveProcessing = async (canvas, videoStream) => {
    const endpoint = await EyePop.workerEndpoint({
        popId: process.env.NEXT_PUBLIC_POP_ID,
        auth: { secretKey: process.env.NEXT_PUBLIC_API_KEY },
    }).connect()

    const renderer = Render2d.renderer(canvas.getContext('2d'), [
        Render2d.renderBox({ showClass: true, showConfidence: true }),
    ])

    const ingress = await endpoint.liveIngress(videoStream)
    const results = await endpoint.process({ ingressId: ingress.ingressId() })

    for await (const result of results) {
        if (canvas.width !== result.source_width) canvas.width = result.source_width
        if (canvas.height !== result.source_height) canvas.height = result.source_height
        renderer.draw(result)
    }
}

Requires a readable MediaStream. If using getUserMedia, handle camera permissions and stream lifecycle cleanly.

---

Step 9 — Visualize Results

Python — with matplotlib

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

with EyePopSdk.workerEndpoint() as endpoint:
    result = endpoint.upload('examples/example.jpg').predict()

with Image.open('examples/example.jpg') as image:
    plt.imshow(image)

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

Node — with @eyepop.ai/eyepop-render-2d

Render bounding boxes and labels onto a canvas. See the Render2d usage shown in Step 8.

---

Step 10 — Authentication Options (Node)

Three patterns, in order of production-readiness:

1. API Key (server-side only) — pass auth: { secretKey }. Never expose this in client code.

2. Session token (recommended for browsers) — generate a short-lived session server-side and hand it to the client.

   // Server
   const session = await endpoint.session()
   res.json(session)

   // Client
   const endpoint = await EyePop.workerEndpoint({ auth: { session } }).connect()

3. Current browser session (dev only) — if the developer is logged into the EyePop Dashboard, use auth: { oAuth2: true } with an explicit popId.

---

Step 11 — Deploy On-Premise (Optional)

For local IP-camera workflows, EyePop supports an on-prem architecture: a lightweight app captures and samples frames from RTSP/HTTP cameras, sends selected frames to the EyePop cloud for inference, and triggers notifications (Twilio, SendGrid, Slack, webhooks). Images can optionally be archived locally for audit or dataset curation.

Benefits:

• Low-latency local dashboard

• Cloud offload for heavy inference (stateless, no server-side storage)

• Pluggable alerting

• Audit-ready image archive

See the On-Premise IP Camera Analysis deployment guide.

---

Tuning Tips

• Auto-start workers: EyePopSdk.endpoint(auto_start=False) (Python) / EyePop.endpoint({ autoStart: false }) (Node) disables automatic worker startup on connect().

• Preserve pending jobs: by default, connect() cancels queued jobs on the worker. Pass stop_jobs=False / stopJobs: false to keep them.

• Keep API keys out of source control: use python-dotenv or Node's dotenv with a .env file.

• Override the API URL: set EYEPOP_URL if you're pointing at a non-production endpoint.

---

Next Steps

• Build a small evaluation set (20–100 images) and iterate

• Chain predictions into a workflow (e.g. detect → crop → classify)

• Move from cloud API to on-prem when latency or data-residency demands it

---

Need Help?

• Docs: https://docs.eyepop.ai

• Dashboard: https://dashboard.eyepop.ai

• Python SDK: https://github.com/eyepop-ai/eyepop-sdk-python

• Node SDK: https://github.com/eyepop-ai/eyepop-sdk-node

• Example projects: https://github.com/eyepop-ai/Labs

Or reach out for help scoping your first production use case.