Extract

Pull structured JSON from a web page or spoken media. For YouTube, podcast feeds, and direct audio/video URLs, Gyrence transcribes the spoken content first; other URLs use the normal HTTP-first fetch pipeline. The resulting text is sent to the extraction model with your prompt and optional schema hint.

Use this when

• You need a few specific fields from a page (price, title, author, contact email) without writing selectors.
• The site's HTML changes often and selector-based scraping is too brittle.
• You want JSON shaped to your own schema, not raw page content.
• You're prototyping enrichment before committing to a per-domain parser.
• You need summaries, quotes, chapters, entities, or other fields from a YouTube video, podcast, or media file.

Request

Example body

{
  "url": "https://example.com/products/widget",
  "prompt": "Extract the product name, price, currency, and availability.",
  "schema": "{\"name\":\"string\",\"price\":\"number\",\"currency\":\"string\",\"inStock\":\"boolean\"}"
}

Audio and video

Extract automatically recognizes supported media URLs; no extra request field is required. It uses this order:

1. YouTube caption track, when available.
2. The newest podcast episode's Podcasting 2.0 transcript (WebVTT, SRT, or JSON), when available.
3. Speech recognition for a direct media URL or podcast enclosure.
4. Normal page retrieval when the URL is not a recognized media target.

The console at /app/extract also accepts audio/video files up to 95 MB. File upload is a console workflow; the public /api/v1/extract contract accepts URLs.

{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "prompt": "Return chapters with title, start time, summary, and notable quotes.",
  "schema": "{\"chapters\":[{\"title\":\"string\",\"startTime\":\"string\",\"summary\":\"string\",\"quotes\":[\"string\"]}]}"
}

Response

{
  "ok": true,
  "data": {
    "url": "https://example.com/products/widget",
    "title": "Widget — Example",
    "extractedJson": "{\"name\":\"Widget\",\"price\":29.99,\"currency\":\"USD\",\"inStock\":true}",
    "via": "http"
  }
}

Example

curl -X POST https://www.gyrence.com/api/v1/extract \
  -H "Authorization: Bearer $GYRENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products/widget",
    "prompt": "Extract the product name, price, currency, and availability.",
    "schema": "{\"name\":\"string\",\"price\":\"number\",\"currency\":\"string\",\"inStock\":\"boolean\"}"
  }'

Errors

{ "ok": false, "error": "Schema must be valid JSON", "code": "bad_request" }

Notes

• Extract uses Gemini 2.5 Flash — chosen for its 3× cost advantage over comparable models at equivalent extraction quality. The API contract (request/response shape) is stable regardless of underlying model; Gyrence may update the model tier over time. The system enforces strict JSON output — no prose, no markdown fences.
• Source pipeline: recognized media uses captions, publisher transcripts, or speech recognition before extraction. Other URLs use the /fetch pipeline: HTTP first, with automatic escalation to the headless browser on any of: origin 403/429/503, network error (status 0), body < 500 chars, JS-shell markers (id="root">, id="__next">, <noscript>, etc.), or post-conversion content loss (HTML ≥ 1000 chars producing < 100 markdown chars). forceBrowser: true skips the HTTP attempt.
• via drives pricing, not the input. Even without forceBrowser, an automatic escalation bills as browser (7 credits).
• SSRF re-validation runs on the final URL after redirects, not just the input.
• No retries on model failure. Garbled output is returned as _raw for your inspection rather than re-prompted server-side.