2257 packet API

Processing version 9 · result field reference · machine-readable spec: /openapi.json · interactive reference: /docs

POST the files of one movie's 2257 records packet. The API combines them into one PDF (the page numbers in every answer refer to it), has a local vision model extract every performer, cuts and checks each ID copy, and serves the result and the PDF back. Extraction takes minutes, so the API is asynchronous: you POST, then poll.

Quick start

# 1. submit the packet: files in page order, plus any metadata you like
curl -s -F "files=@release.pdf" -F "files=@ID front.heic" -F "files=@cast list.xlsx" \
     -F "title=Example Movie 5" -F "scene=1" -F "scene=3" \
     http://127.0.0.1:8257/extractions
# -> 202 {"id": "9f2c…", "status": "queued", ...}   Location: /extractions/9f2c…

# 2. poll every Retry-After seconds until status is done
curl -s http://127.0.0.1:8257/extractions/9f2c…

# 3. fetch the combined PDF
curl -s -o packet.pdf http://127.0.0.1:8257/extractions/9f2c…/pdf

When the server runs with a token, send Authorization: Bearer <token> on every call. This page, /docs, /redoc, /openapi.json and /healthz are readable without it.

Endpoints

Job lifecycle and polling

queued → running → done or failed. One job runs at a time (one GPU); the rest wait in arrival order. A typical packet takes 3 to 10 minutes once it starts.

Poll at the Retry-After interval. Timestamps are ISO 8601 UTC: created, started once running, finished and expires_at once done or failed. Derive queue time and run time from them.

The request

POST /extractions with multipart/form-data.

Files: parts named files

• Send each file as its own part named files. Part order is page order in the combined PDF.
• Accepted types: arw, avif, bmp, cr2, cr3, csv, dng, doc, docx, gif, heic, heif, jp2, jpeg, jpg, jxl, nef, orf, pdf, png, raf, rtf, rw2, tif, tiff, tsv, txt, webp, xlsx. A file's content decides its type, not its name: a .jpg that is really a PNG is read as a PNG (and render_notes says so). Images are read by ImageMagick, so beyond the list above almost any raster format works, including camera RAW (.arw, .cr2, .nef, .dng, ...), HEIC, AVIF and JPEG 2000. Every image is decoded in full before it goes in.
• A file that is no accepted type, or can't be read in full (a truncated JPEG, a broken PDF), is left out of the combined PDF and the job goes ahead without it. Its page_map entry has "pages": [] and excluded with the reason, in the 202 and in the result. Check page_map for excluded; fix the file and re-submit if it matters. Only when no file is usable is the request refused (422 Unsupported File).
• PDF pages go in as-is. Each image becomes one letter-size page (landscape when wider than tall), turned upright, at full resolution: an upright JPEG goes in byte for byte; any other image is converted to a quality-95 JPEG with full color resolution. A multi-page TIFF gives one page per frame; other multi-frame images (an animated GIF) give their first frame, with a render_notes entry. Office and text files are rendered by LibreOffice; spreadsheets print landscape, one page wide, so a row never splits across pages.
• Identical files (same bytes) are included once; page_map lists every uploaded name and the pages it landed on.

Metadata: every other field

• Any field that is not a file is metadata: any keys, any number, none required, no key is special.
• A key sent more than once keeps all its values, returned as a list.
• The model sees the metadata as context from the submitter, labelled as not coming from the documents. Every value it reports must still come from the documents themselves.
• It comes back unchanged as metadata in the 202 and in the result.
• Limits: 50 keys, keys up to 100 characters, values up to 2000. A file part under any name other than files is refused (422 Invalid Metadata) rather than ignored.

The result

A done job returns one JSON document. Keep it: it is self-contained (the ID crop images are inside it) except for the PDF. Every field of it, with a complete example, is explained here.

answer

• pages: the model's inventory, one entry per page, {"page", "what"}, written before anything else.
• performers: one entry per person, with stage names, legal name, date of birth, ID type, number and expiration, production date, every id_copies entry (page, outline box, the fields as printed on that copy) and every documents entry (releases, forms, cast lists).
• unassigned: IDs or forms the model could not tie to a performer. production_date: for the movie as a whole, if stated.
• Page numbers refer to the combined PDF.

Dates

Every date is reported twice: as printed (for example date_of_birth) and parsed (date_of_birth_parsed, ISO YYYY-MM-DD, or null when it can't be read). Numeric dates are read month-first, U.S. style (11/02/1986 is November 2, 05/04/19 is May 4), unless that is impossible (21/11/1986 has no month 21, so it is November 21); two-digit years pivot at 50 (69 is 1969, 30 is 2030), a birth date is never in the future, a production date listing several shoot days gives the earliest, and a date printed without a day rounds the cautious way: a birth date to the last day of its month, an expiration or production date to the first. Examples.

id_crops status

Identity and caching

• The job id is the extraction's identity, which is its inputs. With no metadata it is packet_sha256. With metadata it is a hash of the packet and the metadata, since the metadata changes what the model is told.
• Sending the same files and metadata again while the job exists returns the same id and does not re-extract.
• Sending them again after a failed job retries it. After expiry, or once the processing version has changed, they are processed afresh.

Errors

Every error is RFC 9457 application/problem+json: {"type", "title", "status", "detail", "instance"}, plus extension members where noted.

Processing version

version is one integer for the whole of the processing: assembly, model, prompt, crop checks, date parsing and response shape. It is raised whenever any of that changes what you get back. Each job reports the version that processed it; /healthz reports the current one. The current version is 9.

Limits