Someshot Someshot
Dokumentace Health
Přihlásit
Burda Tools

Someshot — dokumentace API

Veřejné REST API

Přehled

Someshot vytváří screenshoty příspěvků ze sociálních sítí (Instagram, X, Facebook, TikTok). Pošlete URL příspěvku a dostanete hotový obrázek — bez nutnosti tokenů jednotlivých platforem.

API je asynchronní: požadavek POST /api/v1/screenshots zařadí job do fronty a vrátí 202 s job_id a status_url. Stav pak zjišťujete pollingem GET /api/v1/jobs/{job_id}, dokud není done nebo failed.

Výsledky se cachují. Pokud pro stejný požadavek existuje čerstvý screenshot a refresh=false (výchozí), vrátí POST /api/v1/screenshots rovnou 200 s hotovým výsledkem (cached: true) — žádný polling není potřeba.

Base URL (produkce)
https://someshot.burda.tools/api/v1
Base URL (lokál)
https://someshot.localhost/api/v1
Formát
JSON — Content-Type: application/json
Verzování
v cestě: /api/v1

Autentizace

Všechny endpointy pod /api/v1/* vyžadují hlavičku Authorization: Bearer ssk_…. Výjimkou je GET /api/v1/health, který autentizaci nevyžaduje. 

Authorization: Bearer ssk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Chybějící nebo neplatný klíč vrací 401 s kódem UNAUTHORIZED: 

{ "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key." } }

POST /api/v1/screenshots

Vyžaduje Bearer token

Vytvoří job pro screenshot zadané URL. Tělo požadavku je JSON objekt s těmito poli:

Parametr Typ Povinný Rozsah / hodnoty Výchozí Popis
url string ano neprázdná, podporovaná platforma — URL příspěvku (lze i krátký odkaz, např. vm.tiktok.com)
format string ne png · jpeg · webp png výstupní formát obrázku
width integer ne 200–1200 500 šířka v px (CSS)
scale integer ne 1–3 1 device pixel ratio (retina)
theme string ne light · dark light motiv (uplatní se u X a TikTok)
full_text boolean ne true / false true zobrazit popisek (FB show_text / IG captioned)
refresh boolean ne true / false false true = obejít cache a překreslit
callback_url string ne musí být https URL null webhook zavolaný po dokončení (i selhání) jobu

202 Accepted job zařazen do fronty — pollujte status_url: 

{
  "job_id": "9f2c4d6e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "status": "queued",
  "status_url": "https://someshot.burda.tools/api/v1/jobs/9f2c4d6e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}

200 OK cache hit (refresh=false) — výsledek je rovnou hotový, job_id je null a přibývá cached: true (jinak stejná struktura jako odpověď GET /jobs/{job_id}): 

{
  "job_id": null,
  "status": "done",
  "platform": "instagram",
  "created_at": "2026-06-25T10:00:00+02:00",
  "started_at": null,
  "finished_at": null,
  "request": { "url": "…", "format": "png", "width": 500, "scale": 1, "theme": "light" },
  "result": {
    "url": "https://someshot.burda.tools/media/2026/06/ab12cd….png",
    "format": "png", "width": 500, "height": 712, "bytes": 84213,
    "expires_at": "2026-07-25T10:00:04+02:00"
  },
  "error": null,
  "cached": true
}

GET /api/v1/jobs/{job_id}

Vyžaduje Bearer token

Vrátí stav a (po dokončení) výsledek jobu. job_id je UUID vrácené z POST /api/v1/screenshots.

Možné hodnoty status:

queued processing done failed

200 OK — result je vyplněn jen u done, error jen u failed (jinak null): 

{
  "job_id": "9f2c4d6e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "status": "done",
  "platform": "instagram",
  "created_at": "2026-06-25T10:00:00+02:00",
  "started_at": "2026-06-25T10:00:01+02:00",
  "finished_at": "2026-06-25T10:00:04+02:00",
  "request": { "url": "…", "format": "png", "width": 500, "scale": 1, "theme": "light" },
  "result": {
    "url": "https://someshot.burda.tools/media/2026/06/ab12cd….png",
    "format": "png", "width": 500, "height": 712, "bytes": 84213,
    "expires_at": "2026-07-25T10:00:04+02:00"
  },
  "error": null
}

Při status: "failed" nese error kód a zprávu (HTTP zůstává 200 — viz Chybové kódy): 

{ "status": "failed", "result": null, "error": { "code": "RENDER_TIMEOUT", "message": "…" } }

404 Not Found neznámé, neplatné nebo cizí job_id (izolace mezi klíči): 

{ "error": { "code": "NOT_FOUND", "message": "Job not found." } }

GET /api/v1/health

Bez autentizace

Liveness probe. Stav je ok (HTTP 200) jen když je dostupná databáze i render. Pokud je některá komponenta mimo provoz, vrací HTTP 503 a status: "degraded". 

{ "status": "ok", "queue_depth": 3, "render": "up", "db": "up" }

GET /media/{yyyy}/{mm}/{hash}.{ext}

Bez autentizace

Vytvořený obrázek, servírovaný přímo Apachem. URL získáte z pole result.url v odpovědi jobu. Název souboru je neuhodnutelný hash; přístup je read-only přes tuto URL (např. /media/2026/06/ab12cd….png). Platnost obrázku určuje result.expires_at.

Podporované platformy

Platforma platform Domény
Instagram instagram instagram.com
X (Twitter) x x.com, twitter.com
Facebook facebook facebook.com, fb.watch, fb.com
TikTok tiktok tiktok.com, vm.tiktok.com, vt.tiktok.com
Povoleny jsou i subdomény (např. www.instagram.com, m.facebook.com). URL mimo tento seznam vrací UNSUPPORTED_URL.

Chybové kódy

Kód HTTP Význam
VALIDATION_ERROR 400 špatné parametry (chybí url, width/scale mimo rozsah, …)
UNSUPPORTED_URL 400 URL není z podporované platformy
UNAUTHORIZED 401 chybějící nebo neplatný API klíč
NOT_FOUND 404 job neexistuje nebo patří jinému klíči
RATE_LIMITED 429 překročen rate limit klíče (hlavička Retry-After)
QUOTA_EXCEEDED 429 překročena denní kvóta klíče
POST_UNAVAILABLE job příspěvek privátní/smazaný/geoblokovaný
UPSTREAM_BLOCKED job platforma vrátila login wall / blok
RENDER_TIMEOUT job render nestihl timeout
RENDER_FAILED job jiná chyba renderu
Kódy označené job vznikají až při zpracování — vrací se v těle GET /api/v1/jobs/{job_id} jako status: "failed" + error (samotný dotaz má HTTP 200).

Příklady curl

1) Vytvořit screenshot:

curl -X POST https://someshot.burda.tools/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/p/EXAMPLE/", "format": "png", "width": 500, "theme": "light"}'

2) Zjistit stav jobu (polling):

curl https://someshot.burda.tools/api/v1/jobs/9f2c4d6e-1a2b-4c3d-9e8f-0a1b2c3d4e5f \
  -H "Authorization: Bearer YOUR_API_KEY"

3) Health (bez autentizace):

curl https://someshot.burda.tools/api/v1/health