zipir

List video formats (call this before create_lesson when the user names a style) Use when someone asks which styles exist, or before create_lesson if they said a style ("short", "explainer", "vertical"). Returns format ids to pass to create_lesson; never hard-code an id, read it here. No minutes are spent.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

List this account's recent lessons (use when someone asks "my videos", "what did I make", or wants to continue an earlier one) Use when the user refers to their own earlier work: their videos, the lesson they started yesterday, the one waiting for approval. Returns the newest lessons with id, title, status, minutes and a link to open each. Read-only and free. Pass `status` to narrow (queued | rendering | done | failed) and `limit` (default 20, max 50).

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "rendering",
        "done",
        "failed"
      ],
      "description": "Only lessons in this state."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20,
      "description": "How many to return (default 20, max 50)."
    }
  },
  "additionalProperties": false
}

Create a video lesson from a document (use when someone wants a document turned into a video) Use when the user brings a document, PDF, deck, page or text and wants a video, a lesson, an explainer or a summary video of it. Send the file as multipart, or `text`/`url` as JSON. Returns a lesson id immediately; nothing renders until approve_lesson, so creating costs no minutes. Follow it with get_lesson until the storyboard needs approval. With an Idempotency-Key the same request inside 24h returns the same lesson (same key, different body is 409). API documentation: https://zipirapp.com/en/api/

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "The lesson text itself (UTF-8, max 5 MB).",
      "maxLength": 5242880
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "A public http(s) page; its readable text becomes the document."
    },
    "format": {
      "type": "string",
      "enum": [
        "briefing",
        "clay",
        "docwalk",
        "whiteboard",
        "illustrated",
        "intuition",
        "panels",
        "brand",
        "mascothost",
        "timeline",
        "cutaway",
        "mapstory"
      ],
      "description": "Video format. GET /v1/formats lists the live set."
    },
    "title": {
      "type": "string",
      "maxLength": 200,
      "description": "Shown in the panel and used in the download file name."
    }
  },
  "additionalProperties": false
}

Check a lesson's status (poll this after create_lesson and after approve_lesson) Use whenever you need to know where a lesson stands: after creating it, while it renders, or before downloading. `status` is the machine state (queued | rendering | done | failed), `phase` is finer, `needs_approval` is true while the storyboard waits for a human, and `next` says which call to make next. Costs no minutes.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "id"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Approve the storyboard and start rendering (the only call that spends the account's minutes) Use only after the user has seen the storyboard and agreed: this is the panel's approval button. The minutes for the lesson are held at this call and the render is queued. Do not approve on the user's behalf without their go-ahead. Check get_usage first if the balance may be tight.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "id"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Get a signed download link for the finished video (use when the video is ready and the user wants the file) Use once get_lesson says the video is done. Returns a URL (valid 900 s) to the MP4, not the file itself: hand the link to the user or fetch it. `variant=720` is the light copy every plan gets, `variant=1080` is full quality and needs a paid plan.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "id"
    },
    "variant": {
      "type": "string",
      "enum": [
        "720",
        "1080"
      ],
      "default": "1080",
      "description": "variant"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Check remaining video minutes before spending any (call this before approve_lesson if unsure) Use when the user asks how much is left, or before approve_lesson when the balance may be tight. The limit is the account's own entitlement (optionally narrowed per key), never a second rule; `used` counts the minutes of finished videos in the current period.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}