creacortex 0.1.0

Python client for the Creacortex video-creative attention-analysis API

creacortex

Python client for the Creacortex video-creative attention-analysis API.

Upload a video creative, run it through the pipeline, and pull back per-second attention data, a Gen-AI optimization payload, and PDF reports.

Install

pip install creacortex

Quick start

from creacortex import Client

with Client("ace_your_api_key") as cx:
    # one call: upload + start + wait for completion
    run = cx.analyze("ad.mp4", with_audio=True, creative_id="summer-promo")

    csv = cx.get_csv(run.run_id)                 # per-second analysis (bytes)
    payload = cx.get_export(run.run_id)          # Gen-AI insights (dict)
    pdf = cx.get_report(run.run_id, "diagnose")  # PDF report (bytes)

Get an API key from Usage & billing → API keys in the dashboard. It is sent as the X-API-Key header.

Async

import asyncio
from creacortex import AsyncClient

async def main():
    async with AsyncClient("ace_your_api_key") as cx:
        run = await cx.analyze("ad.mp4")
        print(await cx.get_export(run.run_id))

asyncio.run(main())

Step by step

analyze() is a convenience over the raw endpoints, which you can also call directly:

video_id = cx.upload_video("ad.mp4")
run = cx.create_run(video_id, with_audio=True, audience="men 20-45, mobile gamers")
run = cx.wait(run.run_id)                # poll until done (or RunFailedError / WaitTimeout)

for item in cx.list_runs():
    print(item.run_id, item.status, item.ready)

print(cx.get_account().balance)          # credits left

upload_video / analyze accept a file path, raw bytes, or a binary file object.

Errors

Exception	When
AuthError	invalid/missing API key (401)
InsufficientCreditsError	not enough credits (402)
RateLimitError	too many requests (429)
NotFoundError	unknown run (404)
RunFailedError	the run finished with status="failed"
WaitTimeout	wait() exceeded its timeout
ApiError	any other HTTP error (has .status_code)

All inherit from CreacortexError.

Configuration

Client("ace_...", base_url="https://api.creacortex.ai", timeout=60.0)

License

MIT