API Overview¶

Base URL¶

https://api.instatollm.com

Authentication¶

All requests require a Bearer token:

Authorization: Bearer ist_your_token_here

How to get a token →

Endpoints¶

Method	Path	Description
`POST`	`/api/v1/reels/analyze`	Submit a Reel URL for analysis
`GET`	`/api/v1/reels`	List your submitted reels
`GET`	`/api/v1/reels/search?q=...`	Semantic search over your reels
`GET`	`/api/v1/reels/usage`	Token and cost usage summary
`GET`	`/api/v1/reels/:id`	Get analysis result by ID
`DELETE`	`/api/v1/reels/:id`	Delete a reel

CLI¶

For agent and shell workflows, use the vid2llm CLI (cli/ in this repo):

cd cli && make install
vid2llm config init
vid2llm analyze "https://www.instagram.com/reel/..." --wait --json
vid2llm list --limit 10
vid2llm search "pasta recipe"

Request flow¶

Processing is asynchronous:

POST /api/v1/reels/analyze  →  { id: 42, status: "pending" }
                                        ↓
                               (5–90 seconds processing)
                                        ↓
GET /api/v1/reels/42          →  { status: "done", result: {...} }

Status values:

Status	Meaning
`pending`	Job accepted, not started yet
`processing`	Downloading video and calling Gemini AI
`done`	Analysis complete — `result` is populated
`error`	Processing failed — `error` contains the reason

Rate limits¶

Limit	Value
Requests per minute	10
Concurrent jobs	3
Max video duration	90 seconds

Exceeding limits returns 429 Too Many Requests.

Response format¶

All responses are JSON. Successful responses return the resource directly. Errors return { "error": "message" }.

OpenAPI spec¶

The machine-readable OpenAPI 3.0 spec is available at:

https://api.instatollm.com/docs/openapi.yaml

Interactive Swagger UI:

https://api.instatollm.com/docs/index.html