EyePop.ai Python SDK
Python SDK for EyePop.ai's inference and data APIs.
pip install eyepop
Requires Python 3.12+.
Quickstart
from eyepop import EyePopSdk
with EyePopSdk.sync_worker() as endpoint:
result = endpoint.upload('photo.jpg').predict()
print(result)
Set EYEPOP_API_KEY in your environment (get one at dashboard.eyepop.ai), or pass api_key=... to sync_worker():
endpoint = EyePopSdk.sync_worker(api_key='my-api-key', pop_id='my-pop-id')
Configuration
Credentials are read from environment variables. Set one auth method:
| Variable | Description |
|---|---|
EYEPOP_API_KEY |
API key from your dashboard. |
EYEPOP_ACCESS_TOKEN |
Pre-issued OAuth access token. |
Optional:
| Variable | Description |
|---|---|
EYEPOP_POP_ID |
Named pop ID. Defaults to transient. |
EYEPOP_ACCOUNT_ID |
Required for some Data API calls. |
Usage
Single image
from eyepop import EyePopSdk
with EyePopSdk.sync_worker() as endpoint:
result = endpoint.upload('photo.jpg').predict()
print(result)
upload() queues the file; predict() blocks until the result is ready. For videos or multi-frame containers, call predict() in a loop until it returns None.
Binary streams
with EyePopSdk.sync_worker() as endpoint:
with open('photo.jpg', 'rb') as file:
result = endpoint.upload_stream(file, 'image/jpeg').predict()
URLs (HTTP, RTSP, RTMP)
with EyePopSdk.sync_worker() as endpoint:
result = endpoint.load_from('https://example.com/image.jpg').predict()
Videos
with EyePopSdk.sync_worker() as endpoint:
job = endpoint.load_from('https://example.com/video.mp4')
while result := job.predict():
print(result)
Cancel a job mid-stream with job.cancel().
Image groups (multiple images, one result)
Send several images as a single source that the pop processes together as one inference unit — for example a multi-image VLM prompt. The group yields one prediction for the whole set, unlike Batching below, where each image is an independent inference.
with EyePopSdk.sync_worker() as endpoint:
# local files
result = endpoint.upload_group(['a.jpg', 'b.jpg', 'c.jpg']).predict()
# in-memory streams (optional parallel content types)
with open('a.jpg', 'rb') as a, open('b.jpg', 'rb') as b:
result = endpoint.upload_stream_group([a, b]).predict()
# remote URLs (the server fetches each)
result = endpoint.load_from_group([
'https://example.com/a.jpg',
'https://example.com/b.jpg',
]).predict()
Image order is preserved end-to-end. A group may contain up to 16 images (enforced server-side). The pop's ability must be multi-image-capable; a single-image ability handed a group returns an error.
Batching
Queue multiple uploads, then collect results:
file_paths = ['photo1.jpg', 'photo2.jpg']
with EyePopSdk.sync_worker() as endpoint:
jobs = [endpoint.upload(p) for p in file_paths]
for job in jobs:
print(job.predict())
Async with callbacks
import asyncio
from eyepop import EyePopSdk, Job
async def main(paths):
async def on_ready(job: Job):
print(await job.predict())
async with EyePopSdk.async_worker() as endpoint:
for p in paths:
await endpoint.upload(p, on_ready=on_ready)
asyncio.run(main(['photo1.jpg', 'photo2.jpg']))
Visualize results
from PIL import Image
import matplotlib.pyplot as plt
from eyepop import EyePopSdk
with EyePopSdk.sync_worker() as endpoint:
result = endpoint.upload('photo.jpg').predict()
with Image.open('photo.jpg') as image:
plt.imshow(image)
EyePopSdk.plot(plt.gca()).prediction(result)
plt.show()
Composable Pops
Build multi-stage inference pipelines by chaining models. Configure at runtime with endpoint.set_pop(pop).
Components
| Component | Purpose |
|---|---|
InferenceComponent |
Run a model. Supports chunked video via videoChunkLengthSeconds / videoChunkOverlap. |
TrackingComponent |
Track detected objects across frames. |
ContourFinderComponent |
Extract contours from segmentation masks. |
ComponentFinderComponent |
Extract connected components from masks. |
ForwardComponent |
Route outputs between stages. |
Forwarding
CropForward— pass each detection crop to sub-components.FullForward— pass the full image to sub-components.
Both accept includeClasses to filter forwarded detections.
Example: Vehicle → License Plate → OCR
from eyepop.worker.worker_types import (
Pop, InferenceComponent, TrackingComponent, CropForward, MotionModel,
)
pop = Pop(components=[
InferenceComponent(
ability='eyepop.vehicle:latest',
categoryName='vehicles',
confidenceThreshold=0.8,
forward=CropForward(targets=[
TrackingComponent(
maxAgeSeconds=5.0,
motionModel=MotionModel.CONSTANT_VELOCITY,
agnostic=True,
),
InferenceComponent(
ability='eyepop.vehicle.license-plate:latest',
topK=1,
forward=CropForward(targets=[
InferenceComponent(
ability='eyepop.text.recognize.landscape:latest',
categoryName='license-plate',
),
]),
),
]),
),
])
Example: VLM open-vocabulary detection
from eyepop.worker.worker_types import Pop, InferenceComponent, CropForward
pop = Pop(components=[
InferenceComponent(
ability='eyepop.localize-objects:latest',
params={'prompts': [{'prompt': 'person'}]},
forward=CropForward(targets=[
InferenceComponent(
ability='eyepop.image-contents:latest',
params={'prompts': [{'prompt': 'hair color?'}]},
),
]),
),
])
Data Endpoint
Dataset management, VLM inference, and evaluation workflows.
import asyncio
from eyepop import EyePopSdk
async def main():
async with EyePopSdk.dataEndpoint(is_async=True) as endpoint:
datasets = await endpoint.list_datasets()
print(datasets)
asyncio.run(main())
VLM inference on a single asset
from eyepop.data.data_types import InferRequest, TranscodeMode
async with EyePopSdk.dataEndpoint(is_async=True) as endpoint:
job = await endpoint.infer_asset(
asset_uuid='your-asset-uuid',
infer_request=InferRequest(text_prompt='Describe this image.'),
transcode_mode=TranscodeMode.image_cover_1024,
)
while result := await job.predict():
print(result)
Batch dataset evaluation
from eyepop.data.data_types import EvaluateRequest, InferRequest
request = EvaluateRequest(
dataset_uuid='your-dataset-uuid',
infer=InferRequest(text_prompt='How many people are in this image?'),
)
async with EyePopSdk.dataEndpoint(is_async=True, job_queue_length=4) as endpoint:
job = await endpoint.evaluate_dataset(evaluate_request=request)
response = await job.response
print(response.model_dump_json(indent=2))
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file eyepop-3.18.3.tar.gz.
File metadata
- Download URL: eyepop-3.18.3.tar.gz
- Upload date:
- Size: 1.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
64f95c1b8594d3e510f6a5e19cebfa5df3b71eaf37727fe1facfc45aec21829f
|
|
| MD5 |
dbf8bb4bda1d00815b39329e84f448bd
|
|
| BLAKE2b-256 |
4da41eeb25012296d8b056ffbdf1e9bcda7475e64319d09fc6a821d8b6420bfd
|
File details
Details for the file eyepop-3.18.3-py3-none-any.whl.
File metadata
- Download URL: eyepop-3.18.3-py3-none-any.whl
- Upload date:
- Size: 96.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f4f83986be62048381b23a134418515f70ce45232694fa07685cb8d03f008415
|
|
| MD5 |
20316e035308984f9d1e7a03974f4c2f
|
|
| BLAKE2b-256 |
38eec6726da70ae57b3807261e56d88fa47da997571221809ee24525193633e7
|
