Docling-Serve not returning the right format and image description through API

[suung]

Hi there

I am using this requesst

curl -X POST http://XXXX:5001/v1alpha/convert/file \ -F 'files=@testpdf.pdf' \ -F 'options={"from_formats":["pdf"],"to_formats":["json", "doctext"],"image_export_mode":"referenced","do_ocr":false,"force_ocr":false,"ocr_engine":"easyocr","pdf_backend":"dlparse_v4","table_mode":"accurate","pipeline":"standard","document_timeout":604800,"abort_on_error":false,"return_as_file":false,"do_table_structure":false,"include_images":false,"generate_picture_images":false,"generate_page_images":false,"do_picture_description":true,"picture_description_area_threshold":0.05}'

What I want is

• picture descriptions
• json only
• no image

It gives me something starting like (note the markdown and the image

{"document":{"filename":"testpdf.pdf","md_content":"![Image](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAisAAAIACAIAAADMp7uKAAEAAElEQVR4nOz96ZbjRrIlCtvg7gBIxpSZmqq6+951b3/v/zZ9T5+pSqrSkENkMDgAcHcbvh8OMkIplUrndJWUOkVbWikGBxAEQd8ws217o7vDJf4O8QscWPwPPt/hh7uEiACATw997/8I2F7mz98Rn57gz576vbfA9tpn7/1Xd8fhRz/SsofLc75/VBHAHQAcidzdDYgQ2p0E7mDu2GL5HO7gy765uzshIiECuruZIwIitc0u7/Xs3X98Bz/Y3R/5nD/vlT96kP5u8R89eS5xib9HhF/+LT9cRBD/0kO/6fg7fxb/T6xXH+xSW18RCXB55BnWLI86Irjb8kInADxhi4O7t1c4Liuau1l7OZ6ibbr9S/D0Zbv7B/tjcNrK6R58FgDoDmYG7s/BrW0nhCiqJpa6aA6qRpHFvKoRETMygpm5q7sTEaC7iZsycQwBAUVMVYkoMCOiqZu5OyAREp3fDj9ApGV//dkTPrxxOiLgiD+98P+S5z8C/Oje/J1+j883e4lLnONXQKBL/JbilAb8xPrxow/91cXrL650LV95ds8Thjm4GQAiISE6gNSKiCGwqZjq0067IXJAdFqQsb2ckZAcAB3M3AHQ3WqtbifodVA1M0dH4sAh2H9wEfa/fEwucYlLfBAXBPoNx3/0AvVHn+8tpThlOeda2FJVQ4BT7tIewWVDjk9bxGcL7wcFPYfnSAM/LM+dH3oOQqe7PsAhB3cDQHAAJDMzlRBCy7RwecgQvOV10Aps4GAOYC2VIgR3Vam1ZlVz95ZURQ4xRSIAQAQHNzcFJEAEfILgHyDrz8Uad/ixKuivFkv18pKaXOJXjQsC/Xbjb712+LN/T5s/N34Q8fSEH11If1h88h9mAx++Dp+2t1SyTuu7//BdzhgJ7gCiqiLtTzNVrejORGBCSEgIZo7IAABmrgBOrcFjLqXMeZqmMZdZ1RCQkfq+X6/XqR9ijEykpbqpOmAIgPTB0fYf3MQnGP6xT3qJS1zix+KCQL/R+JvCjwP+KDicYOiJC+DgCwQ84w3gciXtAH4Gqg+3d66GnfKs09W3L11/N3dwB8RzT+rpvRGfrtYRiNBUCYCY3eQ4Ho6HQ9/3V5sNAQIhIKoIIBE9pXcEDuaqdZ6O4/FwOO4fd7taSmsvRQ6bzfrFi5d3d3f9sObIjghO1ppPP3p0nj4cnlK9D/gZz4/xxxjPU7p2hP8r9WIv8fHHBYH+0QO/V0TDZ/c9PWWhly10hQ8pBM/

Weirdly enough in the UI it works just perfect

{ "kind": "description", "text": "In this image we can see a woman. She is wearing white color dress.", "provenance": "HuggingFaceTB/SmolVLM-256M-Instruct" } ] }, { "self_ref": "#/pictures/1",

with the following settings

What am I doing wrong? Is there a discrepancy between the API and the UI?

Thanks in advance

There is even a picture description of one picture but that's the only one of 4 pictures

Weirdly enough in the UI this worked just perfect

[dosubot]

Hi @suung! I'm Dosu and I’m helping the docling-serve team.

There is a known discrepancy between the API and the UI in how output is formatted and how options are handled. Both use the same core pipeline, but the UI may apply extra processing to filter out images and present only JSON picture descriptions, while the API tends to serialize the full output—including markdown and embedded images—even if you set include_images to false. This is likely due to differences in how options are propagated and how the final response is serialized in each context.

Recent changes in the codebase (such as the move to ProcessingPipeline) may have affected how these options are interpreted, and the /v1 API (as opposed to /v1alpha) is designed to return JSON by default when using the inbody target kind, which might better match your needs going forward (source).

If you need only picture descriptions in JSON with no images, there may not be a combination of options in the current /v1alpha API that guarantees this output, since the serialization step may still include markdown and images. The UI likely applies additional filtering or formatting not present in the API response path.

If possible, try the /v1/convert/file endpoint with the inbody target kind, as this is intended to return a JSON document and may align better with your requirements. If you continue to see images or markdown, it may require changes to how the API serializes its output or further harmonization between the API and UI code paths.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[suung]

thanks dosu,

the same problem exists after update to v1 with

curl -X POST http://XXX:5001/v1alpha/convert/file \ -F 'files=@testpdf.pdf' \ -F 'options={ "from_formats": ["pdf"], "to_formats": ["json"], "include_images": false, "do_picture_description": true, "create_legacy_output": false }'

returning the image, even with placeholder

[dolfim-ibm]

Which version are you running? If you enable the picture description, you should see the output in all output format. Here is an example of a test markdown, you see 1) caption, 2) picture class, 3) description.