Zıpır MCP

npx add-mcp 'https://api.zipirapp.com/mcp'

Zipir API

Start a video lesson from your own program, follow it, and get the download link.

On this page 7 sections · 5 min read

Short answer: the Zipir API opens the panel's job to your own program: send your key as Authorization: Bearer, turn a document or a text into a lesson, and fetch the finished video's download link. A lesson goes through the same pipeline as the panel's upload: the document is read, a storyboard is prepared, and no frame is produced until you approve the storyboard in the panel.

The key

Connect it yourself. No need to contact us: create the key in the panel and run the code. The first video comes out of your trial minutes; after that the same minute counter as the pricing page — there is no separate API fee.

1. In the panel: Account → API keys → Create key.
2. Keep the key in an environment variable on your server: ZIPIR_API_KEY.
3. Send the first request; you get JSON back and a download link when the video is ready.

Panel → Hesap → API anahtarları → Anahtar oluştur (the panel's own labels, in Turkish). The key starts with zipir_ and is shown once, at creation; the server keeps only its sha256. Every request carries:

Authorization: Bearer $ZIPIR_API_KEY

Keep it in a server-side environment variable. A deleted key stops working at once.

Endpoints

Machine-readable spec: /openapi.json (OpenAPI 3.1). Clients and tool directories read the endpoints from this file.

Base URL https://api.zipirapp.com. Bodies and answers are JSON; uploads are multipart/form-data. 21 formats are live today; GET /v1/formats is the list.

Method	Path	What it does
GET	/v1/formats	The available formats; the live catalog.
GET	/v1/voices	The narrator voices; call before creating a lesson when the user names a voice, a tone or a gender.
GET	/v1/lessons	This account's recent lessons ("my videos", continuing an earlier one).
POST	/v1/lessons	Starts a lesson from a file, text or page URL. 202 and the lesson id.
GET	/v1/lessons/{id}	Status, phase, duration, error; whether the storyboard waits for approval.
DELETE	/v1/lessons/{id}	Stops and deletes the lesson.
POST	/v1/lessons/{id}/approve	Approves the storyboard and starts rendering; the only call that spends the account's minutes.
POST	/v1/lessons/{id}/edit	Changes one scene of a lesson (rewrite, shorten, retitle or restyle); no render starts.
POST	/v1/lessons/{id}/rerender	Renders a finished lesson again; the minutes rule is the same as for approval.
GET	/v1/lessons/{id}/plan	Reads the questions, the answers in force and the plan of a lesson started with interview=true.
POST	/v1/lessons/{id}/answers	Sends the answers to the questions and asks for the plan.
POST	/v1/lessons/{id}/plan/accept	Accepts the plan (or skips the questions with quick); the script and storyboard start.
GET	/v1/lessons/{id}/download	A signed download link (valid for 15 minutes).
GET	/v1/usage	This key's minutes for the period and its per-minute request limit.

MCP: connect an AI assistant

Zipir also runs as an MCP server: from Claude Desktop, Cursor or VS Code you can call the "document to video lesson" tool. One command to install, the same key, the same minute counter.

npx @zipir/mcp

If you would rather not run anything locally, the hosted server is ready at https://api.zipirapp.com/mcp (HTTP, MCP 2025-06-18). Send the same key as Authorization: Bearer zipir_...; the tools, the quota and the minute counter are identical.

The shortest way in Claude: Settings → Connectors → Add custom connector, address https://api.zipirapp.com/mcp. No key to copy: you sign in with your Zipir account (OAuth with PKCE S256), and minutes and approvals work exactly the same.

Configuration (one block, claude_desktop_config.json or Cursor settings):

{
  "mcpServers": {
    "zipir": {
      "command": "npx",
      "args": ["-y", "@zipir/mcp"],
      "env": { "ZIPIR_API_KEY": "zipir_..." }
    }
  }
}

Tools: list_formats, create_lesson, get_lesson, approve_lesson, get_download, get_usage. Package: @zipir/mcp.

Examples

Read the formats:

curl https://api.zipirapp.com/v1/formats \
  -H "Authorization: Bearer $ZIPIR_API_KEY"

Start a lesson from a PDF. The same Idempotency-Key ties a retry to the same lesson (24 hours):

curl https://api.zipirapp.com/v1/lessons \
  -H "Authorization: Bearer $ZIPIR_API_KEY" \
  -H "Idempotency-Key: ohs-2026-10-31" \
  -F "file=@document.pdf" \
  -F "format=briefing" \
  -F "title=OHS induction"

From text or a public page:

curl https://api.zipirapp.com/v1/lessons \
  -H "Authorization: Bearer $ZIPIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Photosynthesis turns light energy into chemical energy in plants."}'

curl https://api.zipirapp.com/v1/lessons \
  -H "Authorization: Bearer $ZIPIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/guide"}'

Follow it and fetch the download link:

curl https://api.zipirapp.com/v1/lessons/LESSON_ID \
  -H "Authorization: Bearer $ZIPIR_API_KEY"

curl "https://api.zipirapp.com/v1/lessons/LESSON_ID/download?variant=720" \
  -H "Authorization: Bearer $ZIPIR_API_KEY"

Minutes left:

curl https://api.zipirapp.com/v1/usage -H "Authorization: Bearer $ZIPIR_API_KEY"

Rules

• Every answer carries x-request-id. Errors have one shape: {"error":{"code","message","request_id"}}.
• A lesson does not start instantly. POST /v1/lessons answers 202; the status moves queued → rendering → done (or failed). While needs_approval is true the storyboard waits in the panel; no frame is produced without that approval.
• Quota is 402, rate is 429. 402 when the key's monthly minutes or the account's own limit is used up; 429 with Retry-After when the per-minute request limit is full.
• A download is a link. Valid for 900 seconds. variant=720 is open to every plan; variant=1080 needs the Studio or Team plan.
• Retries are safe. The same Idempotency-Key returns the same lesson within 24 hours; the same key with a different body is 409.
• A document is 50 MB, a text 5 MB. For documents with personal data the Trust page applies: your document is read only for your video, models are never trained on it.

Pricing

The API is not priced separately; it runs on your panel plan: Studio ₺990/month, 15 finished minutes a month; Team ₺3.490/month, 60 finished minutes a month. VAT included. The unit is a finished video minute. See Pricing.

Example output

You can watch a video made by the same pipeline on the Proof page: a lesson made from Article 17 of Law No. 6331, every sentence of which shows its line in the source.

Last updated: November 12, 2026

---

Kaynak: https://zipirapp.com/en/api/