Skip to main content
When you parse a file, the parsing results include descriptions of images called captions. Captions appear in the markdown field of figure-type chunks. For more information, see Image-Based Chunks. Use the optional custom_prompts parameter to tell how to describe figures during parsing. 
curl -X POST 'https://api.va.landing.ai/v1/ade/parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@document.pdf' \
  -F 'custom_prompts={"figure":"YOUR_CUSTOM_PROMPT"}'

​
When to Add Custom Prompts

Adding custom prompts can be helpful if:
  • The default image descriptions do not fit your use case.
  • The downstream processing tasks require the image descriptions to use a specific format or language.
  • The images or charts are unique to your organization or use case and you need to provide additional context about what they represent.

​
Sample Prompts

Make the description more concise This is helpful if you want to minimize the number of input tokens when running the Split or Extract APIs, or if the images are straightforward and do not need much description. 
custom_prompts={"figure":"Limit the description to 50 characters. Be concise but communicate the core message of the image. Do not truncate sentences."}
Omit the description This is helpful if you don’t need the image descriptions in your post-parsing tasks. 
custom_prompts={"figure":"Do not describe the image. Return an empty string."}
Set the language This is useful if your downstream tasks require descriptions in a specific language. 
custom_prompts={"figure":"Return the description in Spanish."}
Return a specific format This is useful if you want to standardize or change how the image is described. 
custom_prompts={"figure":"If the image is a chart, format the data as an HTML table"}
Use a standard description This is useful if you want to return the same string for every figure. 
custom_prompts={"figure":"Only return this string as the description: This is an image"}

​
Supported Models

The custom_prompts parameter is only supported with . does not generate figure captions, so the parameter does not apply when using that model. Passing it with will return a 422 error. For more information about parsing models, see Document Pre-Trained Transformers (Parsing Models).

​
Requirements

The custom_prompts parameter accepts a JSON string. Only the figure key is supported. Any other key will be rejected. The custom prompt can include up to 512 characters.

​
Use Custom Prompts with the API

curl -X POST 'https://api.va.landing.ai/v1/ade/parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@document.pdf' \
  -F 'custom_prompts={"figure":"Describe axis labels in detail."}'

​
Use Custom Prompts with Our Libraries

​
Parse

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

# Replace with your file path
response = client.parse(
    document=Path("/path/to/file/document"),
    custom_prompts={"figure": "YOUR_CUSTOM_PROMPT"},
)

print(response.chunks)

# Save Markdown output (useful if you plan to run extract on the Markdown)
with open("output.md", "w", encoding="utf-8") as f:
    f.write(response.markdown)

​
Parse Jobs

import time
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

# Step 1: Create a parse job
job = client.parse_jobs.create(
    document=Path("/path/to/file/document"),
    custom_prompts={"figure": "YOUR_CUSTOM_PROMPT"},
)

job_id = job.job_id
print(f"Job {job_id} created.")

# Step 2: Get the parsing results
while True:
    response = client.parse_jobs.get(job_id)
    if response.status == "completed":
        print(f"Job {job_id} completed.")
        break
    print(f"Job {job_id}: {response.status} ({response.progress * 100:.0f}% complete)")
    time.sleep(5)