---
title: "POST /images/page_scrape"
method: POST
path: "/images/page_scrape"
tags: ["Images"]
---

# POST /images/page_scrape

`POST /images/page_scrape`

## Request

- Base URL: `https://alttext.ai/api/v1`
- URL: `https://alttext.ai/api/v1/images/page_scrape`
- Auth: API key in header `X-API-Key`

Crawl and scrape a web page or HTML document, generating alt text for all images on the page. Scraped images will be queued for asynchronous
alt text generation in the background. The API response will contain the details of the parsed images from the HTML (but not
the final generated alt text). The maximum time allowed to download a URL and parse the HTML is 3 seconds. If the source HTML page
is unable to be ingested within that time, the API will return an error response.

NOTE: The crawler *does not* execute Javascript or script tags on the source HTML page. It will only locate HTML `img` elements
in the page source.

## Request body

- object
  - `page_scrape` object
    - `url` string: URL of the page to be scraped. Can be null if you are only sending the `html` param.
    - `html` string: [optional] Raw HTML document to parse. Make sure to properly escape quoted strings, etc.
  - `keywords` string[]: [optional] Array of keywords / phrases to be considered when generating the alt text for each scraped image. Typically only one or two of the keywords from the array will be used in the alt text, but all may be examined when generating the result. Useful for SEO optimized alt text. **Keywords must be in English**, even if requesting alt text in another language
  - `negative_keywords` string[]: [optional] Array of negative keywords / phrases to be removed from any generated alt text. **Negative keywords must be in English**, even if requesting alt text in another language
  - `lang` string: The language(s) for the generated alt text. Use comma-separated language codes (e.g., `"en,es,fr"`). Use one of our <ins>[supported language codes](https://alttext.ai/support#faq-tech)</ins> for this parameter. You can request multiple languages by providing a comma-separated string (e.g. `"en,fr,es"`). **Multi-language behavior:** When requesting multiple languages for an existing image with `overwrite: false` (default when left blank), only missing languages will be generated. Existing alt text in previously generated languages will be preserved. If this parameter is not included, the default language for the account will be used.
  - `include_existing` boolean: If `true`, scraped images that already have alt text will also be processed. Otherwise, images that already have alt text in the HTML will be skipped.

## Response `200`

Successful addition of the image URL and alt text generation.

- PageScrapeResponse
  - `url` string: The page URL that was scraped (can be null if you only send raw HTML).
  - `scraped_images` PageScrapeImage[]: Array of image elements scraped from the page.
    - `src` string: The SRC attribute of the scraped image element.
    - `alt` string: The ALT attribute of the scraped image element. This is the existing alt text in the HTML, if any.
    - `width` integer: The WIDTH attribute of the scraped image element.
    - `height` integer: The HEIGHT attribute of the scraped image element.
    - `skip_reason` string: Why this image was skipped (not processed). If `null`, this image was queued for processing.
  - `total_processed` integer: Number of scraped images that were queued for alt text generation. Scraped images that were not processed will have a `skip_reason` set.
  - `errors` object: Any errors encountered during page scraping.

## Other responses

- `4XX`: The page scrape was not successful.

---

[API](https://skmtc.dev/alttext/apis/alttext-ai-api.md) · [All operations](https://skmtc.dev/alttext/apis/alttext-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/alttext/apis/alttext-ai-api/revisions/6eb62e8e450c?raw)