DeepSeek PDF Upload API: Parsing, Timeouts and Safe Retries

DeepSeek's November 13 application API release lets developers upload documents for questions and answers through deepseek-flash. The upload includes parsing, and a client disconnect does not necessarily stop the work. Before adding PDF chat, decide how your application will track completed files and uncertain upload results.

The release changelog puts file input alongside managed search, URL reading and speech. For document applications, the meaningful change is that parsing and model input can now be handled in one provider's workflow. You still need your own record of what was submitted and whether it succeeded.

Choose file parsing or standalone OCR

Use the Files API when the next step is asking the model about a document. A PDF needs text_recognition or rich_layout_recognition, with purpose before file in the multipart form. user_data is not the PDF upload purpose.

curl https://api.deepseek.com/files \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -F purpose="text_recognition" \
  -F 'expires_after[anchor]=created_at' \
  -F 'expires_after[seconds]=86400' \
  -F file="@manual.pdf"

This documentation-based example sets a one-day file lifetime; it has not been executed here. Omitting expiration keeps the file permanently according to the Files API documentation. Uploaded files are shared across API keys within the account, so do not treat separate keys as separate file libraries.

If your actual requirement is extracting text for another system, use standalone OCR instead. It returns page-level output without storing the document in the Files API or submitting it to a chat model. Check each page's finish_reason: length means its text is incomplete. Also inspect the body for error, since recognition can fail after the HTTP status has already become 200.

Those are different products. A file ID is useful for subsequent model requests; an OCR result is useful when you need to inspect and process the extraction yourself.

Pick the parsing mode deliberately

The file-parsing guide distinguishes text-only extraction from rich layout. Text-only omits figures. Rich layout includes detected figure crops, but detection is not guaranteed and images add input usage.

For a maintenance manual, start with two questions: one answered by a paragraph and one answered only by a diagram. Compare both modes against answers you checked yourself. This is a proposed test, not a reported result. If the diagram answer matters, a convincing paragraph-only answer is not enough to approve the integration.

A returned file ID means parsing succeeded. Keep your own original: the Files API does not let you download either the original document or its parsed result. Reference the ID in a document input, not an image block.

Reconcile a timeout before uploading again

Disconnected clients can leave parsing running. Successful results are stored, billed and listed by GET /files; failed parsing is neither stored nor billed. Your timeout describes what the client knows, not necessarily what the server did.

Keep an upload record with a local document hash, purpose, submission time and eventual file ID. Those are application-side tracking suggestions, not a documented DeepSeek idempotency feature. After an uncertain result, list files and reconcile the returned metadata before another upload. The documented metadata does not include a content hash, so your local hash cannot establish a server-side match. Filename and timestamp matches can remain ambiguous.

If the evidence remains ambiguous, mark the upload unresolved rather than telling the user nothing happened. A retry might be necessary, but it should be a deliberate duplicate-risk decision, not an invisible automatic loop.

A chat request permits 20 documents and 8 MiB of parsed text. Check these separately from upload eligibility.

Separate parsing charges from repeated questions

The pricing page lists $0.225 per 1,000 pages for file parsing. A successful 100-page parse therefore costs $0.0225. Model input and output are separate charges.

Reusing a file avoids another parse fee, but subsequent requests still incur model input charges. For a ten-question workflow, budget the conversation as well as the upload.

Measure the workflow by completed, correct answers per document, not by upload price alone. Cheap parsing is useful only if your application can tell the difference between an unseen file, an unfinished upload and a document the model has actually received.

I’m Paras. I work at the intersection of AI, engineering and distribution.

I help technical teams explain APIs, product tradeoffs and engineering work without turning them into generic marketing.

Book a 30-minute call