With options.acceptRasterFallback: true, pages the regenerate pipeline
can't reconstruct no longer flip the entire upload to a free partial
preview — they're embedded as a tagged <Figure> containing a raster of
the original page, with /Alt populated from the pdftotext slice for
that page.
The default behaviour is unchanged: any page failure still returns
partial: true with no credits deducted. The flag is per-request and
explicit — there's no workspace-wide "always accept fallback" toggle.
When the flag is set and at least one page falls back, the response shape switches to:
{
"partial": false,
"hybrid": true,
"pdfBase64": "…",
"report": {
"pageCount": 5,
"successfulPages": 3,
"rasterFallbackPages": [2, 4],
// …
},
"source": {
"dslJson": "…",
"markdown": null,
"markdownAvailable": false,
"markdownReason": "hybrid output (raster-fallback pages cannot be expressed as markdown)",
},
}
The mix is disclosed in three places so a downstream consumer can
detect it without reading every page: the hybrid: true envelope flag,
the report.rasterFallbackPages list, a visible cover page at the
front of the PDF listing the fallback page numbers, and a
makespdf:hybrid-output = true entry in the document XMP metadata.
The X-Enhance-Outcome response header is hybrid instead of full.
Hybrid is billed at the full per-page rate (1 credit / page across the original page count) — the customer opted in and got a usable PDF. Use it for legacy archive bulk uploads where a hybrid-but-honest output beats no deliverable; stay on the default partial path when you'd rather re-submit the broken page than archive a raster of it.