Post Reefpostreef
Sign inSign up
View as Markdown

What you can extract

Every run starts from a single URL — a video, a photo post or carousel, or an ordinary web page. You decide which inputs we gather and whether our AI engine turns them into structured JSON, or whether you just want the raw files.

The inputs

  • Metadata (always included). The video's identity card: title, author, duration, upload date, view / like / comment counts, description and thumbnail. The base fee covers it, and it's the spine the AI uses to understand what it's looking at.
  • Transcript. Built from the video's captions, in the video's original language. It's the cheapest way to give the AI the full spoken content, and you also get it as a downloadable file.
  • Comments. The video's public comments, fetched as structured data. Good for sentiment, audience questions, corrections and crowd-sourced details the creator never said out loud.
  • Audio analysis. The AI listens to the audio track itself. Use it when captions are missing or unreliable, or when tone, music and delivery matter as much as the words.
  • Full video analysis. The AI watches the video. Anything that's only on screen becomes extractable: text overlays, on-screen ingredients, product shots, visual steps. The audio track is part of the video, so video analysis hears everything audio analysis would.

Limit video analysis by duration

Pass maxVideoDurationSec to opt a single extraction request into a video-input cutoff. For example:

{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "schemaId": "postreef.predefined.recipe.v1",
  "inputs": ["transcript", "comments", "video"],
  "maxVideoDurationSec": 300,
  "auto": true,
  "maxSpendCredits": 2000
}

Post Reef checks the duration itself. 300 seconds or less may use video; over 300 seconds excludes video before downloads and AI fallback. Some platforms (Instagram, for example) don't report a duration up front: Post Reef then downloads the video, measures it, and only uses it if it is within the cutoff. It continues with the other requested inputs. In this example there is no audio input, so longer videos use captions, metadata (including description), and comments only. If those contain too little information, the result can be uncertain rather than retrying with video.

  • Optional integer from 1 to 3,600, in seconds. Omitted means the existing behavior is unchanged, for every account.
  • Requires a schema or schemaId and at least one non-video input; not valid for download-only runs.
  • This limits video, not separately requested audio. Explicit audio may still require downloading media. Omit audio if you want text-only fallback.
  • Pure image posts and webpages are unaffected. Video slides in mixed carousels follow the cutoff.
  • The existing one-hour source cap remains. A video whose length can't be measured after download is excluded.
  • The same policy survives queued dispatch, applies to auto and missing-input fallback, and separates extraction cache entries. Retries must resubmit the same parameter.
  • The probe endpoint accepts the parameter when quoting an AI request, so its quote excludes disallowed video. Actual billing uses the inputs used. Text still has a duration-based cost; choose a budget sufficient for your supported source length.

Limit comment downloads

Pass maxComments in your API request to download fewer comments: an integer from 1 to 1,000, including replies. The default is 1,000. For example, maxComments: 50 gives a recipe extractor useful context without paging through hundreds of comments. AI reads up to 30 of the downloaded comments, ranked by likes.

This applies to both download-only and AI runs. It limits pagination where the provider supports it; fewer comments may be available. The flat comments charge stays the same. To skip comments entirely, leave "comments" out of inputs (AI) or parts (downloads).

Not just videos

  • Photo posts and carousels. An Instagram photo or a TikTok slideshow has no video to download, so the run extracts from its images and caption instead: the AI reads every slide alongside the metadata and comments, and the images come back as downloadable files. Video and audio inputs simply don't apply.
  • Articles and web pages. A URL with no video at all takes the article path: we fetch the page, keep the readable text and images, and run the same schema extraction over them. The page text takes the transcript's place — you get it as a file too — and the run is priced flat (see pricing).

Two ways to run

  • Downloads only (no AI). We fetch the video and its artifacts (metadata, thumbnail, transcript, comments, audio) and hand you the files. No schema and no AI charge: you pay the base fee and the download rates for the artifacts you pick.
  • AI extraction. You pick the inputs and a schema (one of ours, or your own: see custom schemas). Our AI engine reads everything you selected and returns one JSON object that conforms to the schema. You still get all the downloaded files alongside the extraction.

What you get back

Every completed run gives you a results page with two things:

  • Files. The video, audio track, transcript, comments, thumbnail and metadata — plus the images of a photo post or carousel, or the page text of an article — each individually downloadable.
  • Structured JSON. For AI runs, the extraction result: a single object matching your schema, viewable in the browser and downloadable as a file.

Not every video has every artifact: some have no captions, some have comments disabled. We extract whatever exists and tell you what was skipped; missing extras never fail your run.

When the video doesn't match

Sometimes a video isn't about what your schema describes: a robotics clip run against a recipe schema, say. Rather than invent hollow data, the AI returns a content-match verdict:

  • ok. The content matched, so you get the structured extraction.
  • no_match. The video is clearly about something else. The extraction is null and a short verdictReason explains it.
  • uncertain. There wasn't enough in the inputs you chose to decide (a silent visual demo when you only asked for the transcript, say). Null extraction, with a reason. Try richer inputs like audio or full video.

On the API this is the outcome field on the extraction and its result/webhook payloads. Always check it before treating a null extraction as an empty result.