Custom image provider

ContentBeamer can source a site's video slide images from your own API instead of a diffusion model. Renderers beat generated imagery wherever the domain has structure — circuit simulators, chart engines, chemistry structures, music notation, maps — because typeset text can't be misspelled and displayed values can be real measurements. Available on Pro and Agency plans, per site, under Site Settings → Custom Image Provider.

Your endpoint is called server-side with SSRF protection. Private ranges and link-local addresses are rejected before the request is made.

The request

ContentBeamer POSTs JSON to your endpoint. The prompt describes the desired visual and includes the slide's narration for context. Your configured auth header is attached to every request.

POST https://your-api.example.com/render
Content-Type: application/json
<your-auth-header>: <your-secret>

{
  "prompt": "A circuit diagram showing ... Narration spoken over this image: \"...\"",
  "width": 1920,
  "height": 1080,
  "format": "png"        // or "gif" when the user requests an animated slide
}

The response

200 OK
{
  "pngUrl": "https://...",      // publicly fetchable PNG — or use pngBase64
  "pngBase64": null,            // inline alternative (one of the two is required)
  "gifUrl": null,               // format:"gif" only — the animated loop
  "gifBase64": null,            //   (pngUrl/pngBase64 then carry the poster frame)
  "title": "Half-wave rectifier",          // optional
  "narration": "This circuit converts..."  // optional spoken explanation — offered
}                                          //   to the editor, never applied silently

4xx / 5xx
{ "error": "human-readable message" }      // shown verbatim in the editor

Requirements & limits

https only, port 443, public hostname. Private/internal addresses are rejected, redirects are not followed, and responses are capped at 25MB.
Answer within 3 minutes. Slow cold-starts are fine; hangs are aborted.
Return real PNG/GIF bytes. Content is magic-byte checked before being re-hosted in ContentBeamer's storage.
Correctness is yours. ContentBeamer validates the contract shape, not your domain output. We recommend verifying claims against your renderer before responding — e.g. compare requested values with simulated measurements and regenerate on mismatch.
Your images are reviewed. Every returned image passes a vision-model quality gate before it reaches a slide. A rejected image triggers exactly one retry whose prompt ends with "Your previous image was rejected: <problem>. Fix exactly this." — handle it like any other request. If the retry is also rejected, the image is kept but the user sees a warning naming the problem.

Design guidance (learned the hard way)

Ground the visual in the narration. The prompt includes the exact sentences spoken over your image — illustrate that claim, not the general topic. A technically-on-topic visual that ignores the narration reads as unrelated.
Match the visual language to the scene. An introduce-the-object scene wants a labeled figure; a how-it-scales scene wants a relationship chart. Consider letting your spec model choose between modes.
Label everything and render text as text. Typeset labels and legends are the whole advantage of a renderer over a diffusion model.
Design for phone-size playback. Thin hairlines and low-contrast content vanish under video compression at feed size.

How it appears in the product

Once configured and tested, every slide in the video editor gets a "⚡ <your provider name>" button. The slide's feedback box becomes the prompt; returned images behave like any other slide image (pinned across re-renders, editable, replaceable). If your response includes a narration, the editor offers it to the user as a suggested voiceover for that slide. Director's Notes can also route image operations to your provider.