lightreel 0.1.1

Tiny client + CLI for the Lightreel API (api.lightreel.ai). Ask Lightreel questions from your code or terminal.

lightreel

The API to answer any social media questions.

Tiny client + CLI for the Lightreel API. Ask Lightreel questions from your code or terminal.

Ask about TikTok and Instagram, find trends, creators, and more.

Zero dependencies (standard library only). Works as an import and as a CLI.

Install

pip install lightreel
# or run the CLI without installing:
pipx run lightreel "find me the top fitness hooks this week"

Use it in code

from lightreel import Lightreel

client = Lightreel(api_key="lr_live_xxx")  # or set LIGHTREEL_API_KEY

# Plain question
res = client.chat(question="find me the top fitness hooks this week")
print(res["answer"])           # prose string
print(res["conversationId"])

# Continue the conversation
client.chat(question="give me 5 more", conversation_id=res["conversationId"])

# Structured output (max 5 fields) — "answer" comes back as a dict
out = client.chat(
    question="find me the top fitness hooks this week",
    response_fields={
        "hooks":   {"type": "array",  "description": "the hook lines"},
        "summary": {"type": "string", "description": "one-paragraph recap"},
    },
)
print(out["answer"]["hooks"])

# History
client.list_chats()
client.get_chat(res["conversationId"])

Requests default to a 20-minute timeout because /v1/chat runs the agent live and can take a few minutes. Override with Lightreel(timeout=seconds).

Use it in the terminal

export LIGHTREEL_API_KEY=lr_live_xxx

lightreel "find me the top fitness hooks this week"
lightreel "give me 5 more" -c <conversationId>
lightreel "top fitness hooks" -f "hooks:array:the hook lines" -f "summary:string:one-paragraph recap"
lightreel list
lightreel get <conversationId>

Flag	Meaning
-k, --key	API key (or LIGHTREEL_API_KEY)
-c, --conversation	continue an existing conversation
-f, --field name:type:description	request structured output (repeatable, max 5; type = string|array)
--json	print the raw JSON response

Errors

Non-2xx responses raise LightreelError with .status and .type.