openapi: 3.1.0
info:
version: 1.9.6
title: AltText.ai API
description: |-
### How to Use the AltText.ai API
The AltText.ai API is a set of REST endpoints that accept `JSON`, and in some cases `multipart/form-data`, requests.
#### API Endpoint:
All API requests go to our API endpoint: `https://alttext.ai/api/v1`
#### Authentication via API Key
Every API call is authenticated using an API key sent in the `X-API-Key` request header.
#### Rate Limiting
Some API calls may be rate-limited. If rate limits are reached, you will receive a `429 Too Many Requests` response.
See the specific request details to find out if rate limiting is implemented for the request.
#### Language Support
The API supports generating alt text in multiple languages. You can request alt text in one or more languages by using the `lang` parameter.
- Request multiple languages by providing a comma-separated string (e.g., `en,fr,es`)
- Each additional language beyond the first consumes one translation credit per image
- If not specified, the account's default language will be used (usually English)
- **Note**: The `gpt_prompt` and `keywords` parameters must be provided in English, even when requesting translations
##### Example Request:
```
curl -X GET "https://alttext.ai/api/v1/images/your-asset-id" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"lang": "en,es,fr"}'
```
You can create your API key by going to the [API Keys](https://alttext.ai/account/api_keys) section of your account.
summary: |-
#### [AltText.ai](https://alttext.ai) generates alt text for images without the need of a human copywriter.
We use AI and deep learning computer vision models to accurately create alternative text for images.
contact:
name: AltText.ai
license:
name: MIT
url: 'https://spdx.org/licenses/MIT.html'
servers:
- url: 'https://alttext.ai/api/v1'
tags:
- name: Images
description: |
Images are objects which have alt text, and together comprise your "library".
You can create an image in your library by passing either a URL to a publicly-available
image on the web, or by uploading the binary file data for an image on your local system. Every image is assigned a unique `asset_id`
either automatically, or provided by you, and this can be used in subsequent API calls for the specific image.
AltText.ai will attempt to generate alt text for any image you add to your library.
It's important to note that we never store the actual image after the alt text is generated.
- name: Account
description: Get and set your various Account settings using these APIs.
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
schemas:
Subscription:
type: object
properties:
plan_name:
type: string
description: The name of your current subscription plan.
usage_quota:
type: integer
description: The number of credits granted each billing period on this plan.
status:
type: string
description: The current status of the subscription plan.
expires_at:
type: string
description: The renewal / expiration date of the plan.
Account:
type: object
properties:
name:
type: string
description: The name of your account.
maxLength: 512
webhook_url:
type: string
description: "[optional] The notification URL to use for webhooks."
maxLength: 1024
notification_email:
type: string
description: "[optional] The email address to notify for important transactional events, such as low credit balance."
usage:
type: integer
description: The number of credits used this billing period.
usage_limit:
type: integer
description: The maximum number of credits that can be used during this billing period (includes any rollover credits).
whitelabel:
type: boolean
description: |
Whether this account is marked as being a whitelabel account. When whitelabel is `true`, integrations for this account
(e.g. WordPress, Shopify, etc) will not display the plan name being used. This is useful if you are installing
AltText.ai on behalf of other clients who do not need to know your plan details. You can update this setting
only on the AltText.ai website.
ending_period:
type: boolean
description: |
Whether to add a period to the end of each generated alt text. This setting can only be updated
on the AltText.ai website.
no_quotes:
type: boolean
description: |
Whether to remove single and double quote characters from the generated alt text. This setting can only be updated
on the AltText.ai website.
remove_symbols:
type: array
items:
type: string
description: |
A list of symbol characters which should be removed from the generated alt text.
gpt_prompt:
type: string
description: |
The default Final Pass prompt: a prompt of your own that runs on each alt text after it is generated. Prompts must be written in English,
even if alt text is being generated in another language.
max_chars:
type: integer
description: Maximum character limit for alt text, if set on the account. A value of `null` means alt text will be generated using the default limits of the AI model.
subscription:
description: The associated subscription plan, if any.
$ref: '#/components/schemas/Subscription'
errors:
type: object
description: Any errors associated with the account. Note - This will be an empty object for valid account data.
AccountUpdate:
type: object
properties:
name:
type: string
description: The name of your account.
maxLength: 512
webhook_url:
type: string
description: "[optional] The notification URL to use for webhooks."
maxLength: 1024
notification_email:
type: string
description: "[optional] The email address to notify for important transactional events, such as low credit balance."
Image:
type: object
properties:
asset_id:
type: string
description: The unique ID of the image.
maxLength: 128
url:
type: string
description: The URL of the image. Will be `null` if the image was added via raw file upload.
maxLength: 2048
alt_text:
type: string
description: The assigned alt text of the image.
maxLength: 1024
alt_texts:
type: object
description: Alt text in requested languages, with language codes as keys.
tags:
type: array
description: Words or phrases that you want to associate with the image.
metadata:
type: object
description: Any custom information you want to store. This will be passed back on all API requests and webhooks.
created_at:
type: integer
description: 'Creation date of the image, in seconds since epoch.'
errors:
type: object
description: Any errors associated with this image. Note - This will be an empty object for valid images.
error_code:
type: string
default: null
description: An identifier describing the type of error, if any.
enum:
- insufficient_credits
- invalid_params
- general
ImageCreate:
type: object
properties:
url:
type: string
description: The URL of the image that needs alt text. Either `url` or `raw` is *required* to be sent.
raw:
type: string
description: The base64-encoded image data, used when sending a local file that is not reachable via public URL. Encoding should conform to RFC 4648, with no line feeds. Either `url` or `raw` is *required* to be sent.
asset_id:
type: string
description: 'optional: Your own unique asset ID to use for this image. If not specified, a unique value will be automatically created. Cannot contain any of these characters: `?&#\/%<>+`'
tags:
type: array
description: 'optional: Words or phrases associated with the image.'
metadata:
type: object
description: 'optional: Any custom information you want to store. This will be passed back on all API requests and webhooks.'
ImageUpdate:
type: object
properties:
asset_id:
type: string
description: 'New asset ID for this image. Must be unique across all other images. Cannot contain any of these characters: `?&#\/%<>+`'
maxLength: 128
alt_text:
type: string
description: Updated alt text for the image.
maxLength: 1024
metadata:
type: object
description: 'optional: Any custom information you want to store. This will be passed back on all API requests and webhooks.'
ImagesResponse:
type: object
properties:
images:
type: array
items:
$ref: '#/components/schemas/Image'
BulkUpload:
type: object
properties:
success:
type: boolean
description: Whether the upload was successfully processed.
rows:
type: integer
description: Number of rows processed from the uploaded CSV file.
maximum: 100000
row_errors:
type: array
description: Array of [rowNumber, errorMessage] arrays indicating rows which had errors, if any.
items:
type: array
items:
- type: integer
- type: string
error:
type:
- string
- 'null'
description: 'Error message preventing the file from being processed, if any.'
PageScrapeImage:
type: object
properties:
src:
type: string
description: The SRC attribute of the scraped image element.
alt:
type: string
description: The ALT attribute of the scraped image element. This is the existing alt text in the HTML, if any.
width:
type: integer
description: The WIDTH attribute of the scraped image element.
height:
type: integer
description: The HEIGHT attribute of the scraped image element.
skip_reason:
type: string
description: Why this image was skipped (not processed). If `null`, this image was queued for processing.
PageScrapeResponse:
type: object
properties:
url:
type: string
description: The page URL that was scraped (can be null if you only send raw HTML).
scraped_images:
type: array
items:
$ref: '#/components/schemas/PageScrapeImage'
description: Array of image elements scraped from the page.
total_processed:
type: integer
description: Number of scraped images that were queued for alt text generation. Scraped images that were not processed will have a `skip_reason` set.
errors:
type: object
description: Any errors encountered during page scraping.
WebhookPayload:
type: object
properties:
event:
type: string
description: The event name which occurred.
enum:
- uploaded
- deleted
schema_ver:
type: string
description: The version of the webhook JSON payload in this request.
timestamp:
type: integer
description: When this event occurred, in seconds-since-epoch.
data:
description: The webhook event payload.
$ref: '#/components/schemas/ImagesResponse'
security:
- ApiKeyAuth: []
paths:
/account:
get:
operationId: get-account
tags:
- Account
description: Get account settings.
responses:
'200':
description: Successful retrieval of the account data.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
example:
name: XYZ Corp
webhook_url: 'https://my.domain.com/webhooks/alttextai'
notification_email: "alerts@xyzcorp.com"
usage: 23
usage_limit: 100
whitelabel: false
ending_period: true
no_quotes: false
remove_symbols: ["#", "%"]
gpt_prompt: null
max_chars: 200
subscription:
plan_name: "Bronze Plan (Monthly)"
usage_quota: 100
status: "active"
expires_at: "2023-01-23T13:48:07.465Z"
errors: {}
put:
operationId: update-account
tags:
- Account
description: Update settings of your account.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
account:
type: object
$ref: '#/components/schemas/AccountUpdate'
examples:
Update the webhook notification URL for your account:
value:
account:
webhook_url: 'https://my.domain.com/webhooks/alttextai'
Update your account name:
value:
account:
name: 'My New Company'
responses:
'200':
description: Successful update of your account details.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
example:
name: XYZ Corp
webhook_url: 'https://my.domain.com/webhooks/alttextai'
notification_email: "alerts@xyzcorp.com"
usage: 23
usage_limit: 100
whitelabel: false
ending_period: true
no_quotes: false
remove_symbols: ["#", "%"]
gpt_prompt: null
max_chars: 200
subscription: null
errors: {}
4XX:
description: Invalid request. See account errors field for details.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
example:
name: XYZ Corp
webhook_url: 'https://oops'
notification_email: null
usage: 23
usage_limit: 100
whitelabel: false
ending_period: true
no_quotes: false
remove_symbols: ["#", "%"]
gpt_prompt: null
max_chars: 200
subscription: null
errors:
webhook_url:
- is not a valid URL
/images:
get:
operationId: get-images
tags:
- Images
description: Get data about existing images. This request supports pagination using the 'page' and 'limit' parameters.
parameters:
- name: page
in: query
description: Controls the page of results to be returned. Page values start with 1.
required: false
schema:
type: integer
default: 1
- name: limit
in: query
description: Controls the number of results per page. Maximum 100.
required: false
schema:
type: integer
default: 20
- name: url
in: query
description: Filter for a specific image URL. Must be an exact match; no wildcards or regex (yet).
required: false
schema:
type: string
responses:
'200':
description: Successful retrieval of the images
headers:
link:
description: The web-standard link header for pagination, as defined in [RFC-8288](https://tools.ietf.org/html/rfc8288)
schema:
type: string
current-page:
description: The current page number of the results. Page numbers start at 1.
schema:
type: integer
page-items:
description: The number of items per page of results.
schema:
type: integer
total-pages:
description: The total number of pages in the result set.
schema:
type: integer
total-count:
description: The total number of items (across all pages) in the result set.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesResponse'
example:
images:
- asset_id: ea9edd7e217cf2805a803c23c2517b68
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
alt_text: A monarch butterfly
alt_texts:
en: A monarch butterfly
tags:
- insect
- butterfly
created_at: 1662643276
errors: {}
error_code: null
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Details about the error encountered.
example:
error: 'expected :items >= 1; got 0'
x-internal: false
post:
operationId: create-image
tags:
- Images
description: |
Add an image and generate alt text.
There are two ways to add an image:
- Adding an image **by URL**:
- The URL to your image must be publicly accessible.
- Include the `url` field in your image JSON data. *DO NOT* include the `raw` field.
- Adding an image by **sending a base64-encoded binary file**:
- Use this method when your image is not accessible via URL (e.g. a local file).
- Include the `raw` field in your image JSON data. *DO NOT* include the `url` field.
- The `async` parameter is *not* supported for binary file uploads. All raw file uploads are processed synchronously.
**Rate Limited**: Requests are limited to 4 calls per second.
**Duplicate images**: If you try to add a URL which already exists in your library, the existing image data will be returned
with a success response. You will *not* be charged any credits in this case. No webhook event will be sent, even if you requested `async`.
**Note**: Image files are *never* stored permanently by AltText.ai. We simply store the URL you send for the image,
and use that to temporarily fetch the image for analysis. After fetching the image, it is deleted and never persisted on our servers.
If you upload an image file instead of a URL, the image is deleted immediately after being analyzed.
#### Image requirements
- Supported formats: JPEG, PNG, GIF, WEBP, BMP
- Maximum file size: 16 MB
- Minimum dimensions: 50 x 50 (smaller images may not be able to generate alt text).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
image:
type: object
$ref: '#/components/schemas/ImageCreate'
async:
type: boolean
default: false
description: 'Whether to add the image in the background or immediately (synchronously). When `async` is true, the API response will always be successful with an empty response body. Use webhooks to be notified when the image is added.'
ecomm:
type: object
description: |
[optional] The ecommerce data to use when generating alt text specific to an ecommerce product.
Providing the product and optional brand or color name will use our ecomm-specific vision system,
which will include your product details in the generated alt text.
required:
- product
properties:
product:
type: string
description: The name of the product in the image.
brand:
type: string
description: '[optional] The brand name of the product in the image.'
color:
type: string
description: '[optional] The specific color of the product in the image.'
gpt_prompt:
type: string
maxLength: 768
description: |
[optional] A Final Pass prompt to run on the initially generated alt text. Be sure to include the `{{AltText}}` macro enclosed in two curly braces --
we will substitute this macro with the initially generated alt text, then run your prompt. The result will be returned as the alt text for the image.
Prompts must be written in English, even if alt text is being generated in another language.
Example prompt: *"Rewrite the following text in the style of William Shakespeare: {{AltText}}"*
keywords:
type: array
maxItems: 6
items:
type: string
description: |
[optional] Array of keywords / phrases to be considered when generating the alt text. 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
keyword_source:
type: string
minLength: 12
maxLength: 1024
description: |
[optional] Text to use as the source of keywords for the alt text. This field will *only* be used
if the `keywords` argument is blank. This text might be a product description, or a paragraph that
describes the context of the images, etc.
lang:
type: string
default: en
description: |
The language(s) for the generated alt text. Use comma-separated language codes (e.g., `"en,es,fr"`). Use one of our [supported language codes](https://alttext.ai/support#faq-tech) 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.
max_chars:
type: integer
default: null
minimum: 80
maximum: 500
description: |
[optional] Maximum length of the generated alt text. If not specified, your account default value will be used.
model_name:
type: string
default: null
enum:
- describe-detailed
- describe-regular
- describe-factual
- succinct-describe-factual
- describe-terse
description: |
[optional] The language model to use for alt text generation. See our documentation for details
on each of these models. The model name strings correspond to the models below:
* `describe-detailed` => Elaborated model
* `describe-regular` => Standard model
* `describe-factual` => Matter-of-fact model
* `succinct-describe-factual` => Concise model
* `describe-terse` => Terse model (usually less than 120 characters)
negative_keywords:
type: array
maxItems: 6
items:
type: string
description: |
[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
overwrite:
type: boolean
default: false
description: |
If `true`, any existing image with the same URL or asset ID (if provided) will be overwritten with new result data.
This parameter will force a regeneration of the alt text for an existing image.
timeout_secs:
type: integer
default: 12
minimum: 5
maximum: 30
description: |
[optional] The maximum timeout, in seconds, to wait for alt text to be generated.
It is *strongly recommended* to leave this at the default value unless you are prepared to deal
with results that may not have alt text, or take longer than usual to be returned.
webhook_url:
type: string
default: null
description: |
[optional] Alternative webhook URL for notifications for this operation.
* If this parameter is not set or has a value of `null`, then the default notification URL for the account will be used.
* When this parameter is set, webhooks will be sent here *instead* of the default notification URL on the account.
* If your account has a default notification URL set, but you do not want any webhooks sent for this operation, you can pass an empty string `""` as the value of this parameter.
examples:
Add an image using only a URL:
value:
image:
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
Add an image by sending base64-encoded file data:
value:
image:
raw: 'dGhlIHF1aWNrIG ... GRvZy4='
Add an image with url and your own asset identifier:
value:
image:
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
asset_id: butterfly-123456
Add an image with ecommerce data:
value:
image:
url: 'https://upload.wikimedia.org/wikipedia/commons/6/67/RolexDaytona.jpg'
ecomm:
product: Daytona
brand: Rolex
color: Jet Black
Add an image and run a Final Pass prompt:
value:
image:
url: 'https://upload.wikimedia.org/wikipedia/commons/6/67/RolexDaytona.jpg'
gpt_prompt: "Rewrite the following text in the style of Shakespeare: {{AltText}}"
Add an image and get alt text in multiple languages:
value:
lang: "en,es,fr"
image:
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
Add an image with keyword tags:
value:
image:
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
tags:
- insect
- butterfly
Add an image with url and some custom metadata:
value:
image:
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
metadata:
internal_id: 123
kingdom: Animalia
phylum: Arthopoda
class: Insecta
responses:
'200':
description: Successful alt text generation.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
example:
asset_id: ea9edd7e217cf2805a803c23c2517b68
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
alt_text: A monarch butterfly
alt_texts:
en: A monarch butterfly
es: Una mariposa monarca
fr: Un papillon monarque
metadata:
internal_id: 123
kingdom: Animalia
phylum: Arthopoda
class: Insecta
created_at: 1662643276
errors: {}
error_code: null
'429':
description: Too many requests. Rate limit exceeded.
4XX:
description: Invalid request. See image errors field for details.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
example:
url: 'https://bad.images.com/does-not-exists.jpg'
errors:
url:
- Image URL is not accessible.
error_code: "general"
'/images/{asset_id}':
get:
operationId: get-image-by-asset-id
tags:
- Images
description: Retrieve information about an existing image
parameters:
- name: asset_id
in: path
required: true
description: The asset ID of the image to retrieve.
schema:
type: string
responses:
'200':
description: Successful retrieval of the image data
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
example:
asset_id: ea9edd7e217cf2805a803c23c2517b68
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
alt_text: A monarch butterfly
alt_texts:
en: A monarch butterfly
tags:
- insect
- butterfly
metadata:
internal_id: 123
kingdom: Animalia
phylum: Arthopoda
class: Insecta
created_at: 1662643276
errors: {}
error_code: null
'404':
description: Image not found
put:
operationId: update-image-by-asset-id
tags:
- Images
description: |
Update an image with new data.
**Note**: You cannot update the URL of an exist image.
parameters:
- name: asset_id
in: path
required: true
description: The asset ID of the image to update.
schema:
type: string
maxLength: 128
- name: lang
in: query
required: false
schema:
type: string
default: en
description: |
The language(s) for the updated alt text. Use one of our [supported language codes](https://alttext.ai/support#faq-tech) for this parameter.
You can request multiple languages by providing a comma-separated string (e.g. `"en,fr,es"`).
**Multi-language behavior:** When updating alt text for multiple languages with `overwrite: false` (default when left blank), only missing languages will be updated. Existing alt text in previously generated languages will be preserved.
- name: overwrite
in: query
required: false
schema:
type: boolean
default: false
description: |
When `false` (default), existing alt text in the specified language(s) will be preserved. When `true`, existing alt text will be overwritten with the new value.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
image:
type: object
$ref: "#/components/schemas/ImageUpdate"
examples:
Updating alt text of an image:
value:
image:
alt_text: The endangered monarch butterfly in a field of clovers.
Updating the asset ID of an image:
value:
image:
asset_id: monarch-1
responses:
'200':
description: Successful update of the image.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
example:
asset_id: monarch-1
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
alt_text: The endangered monarch butterfly in a field of clovers.
alt_texts:
en: The endangered monarch butterfly in a field of clovers.
tags:
- insect
- butterfly
metadata:
internal_id: 123
kingdom: Animalia
phylum: Arthopoda
class: Insecta
created_at: 1662643276
errors: {}
error_code: null
4XX:
description: Invalid request. See image errors field for details.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
example:
asset_id: butterflies/monarch+1
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
alt_text: A monarch butterfly
created_at: 1662643276
errors:
asset_id:
- contains invalid characters
error_code: "general"
delete:
operationId: delete-image-by-asset-id
tags:
- Images
description: Delete an image.
parameters:
- name: asset_id
in: path
required: true
description: The asset ID of the image to delete.
schema:
type: string
responses:
'200':
description: Successful deletion of the image data
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
example:
asset_id: ea9edd7e217cf2805a803c23c2517b68
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
alt_text: A monarch butterfly
alt_texts:
en: A monarch butterfly
tags:
- insect
- butterfly
metadata:
internal_id: 123
kingdom: Animalia
phylum: Arthopoda
class: Insecta
created_at: 1662643276
errors: {}
error_code: null
'404':
description: Image not found
/images/search:
get:
operationId: search-images
tags:
- Images
description: |
Search for images in your library. This request supports pagination using the `page` and `limit` parameters.
You can search by:
- **Alt text content**: Search for words or phrases in alt text (default behavior)
- **Asset ID**: Find a specific image by its unique identifier
- **URL**: Search by image URL substring
The search automatically detects the query type based on its format.
parameters:
- name: q
in: query
description: |
The search query (URL escaped). The search type is automatically detected:
**URL Search**: If the query starts with `http://` or `https://`, it searches by URL substring.
- Example: `https://cdn.example.com/products` finds all images with URLs containing that string.
**Asset ID Search**: For other queries, the system first tries to find an exact asset ID match.
- Example: `shp-12345` or `my-custom-id` will find the image with that asset ID.
**Alt Text Search** (fallback): If no asset ID matches, the query searches alt text content.
- Supports standard web search operators:
* `&` (logical AND). Example: `apple & banana` matches "A bowl of apples with a banana on top".
* `|` or `OR` (logical OR). Example: `apple | banana` matches both "A green apple" and "A yellow banana".
* `-` or `!` (logical exclusion). Example: `apple -banana` matches "A green apple" but not "A bowl of apples with a banana on top."
required: true
schema:
type: string
maxLength: 256
- name: page
in: query
description: Controls the page of results to be returned. Page values start with 1.
required: false
schema:
type: integer
default: 1
- name: limit
in: query
description: Controls the number of results per page. Maximum 100.
required: false
schema:
type: integer
default: 20
responses:
'200':
description: Successful image alt text results returned.
headers:
link:
description: The web-standard link header for pagination, as defined in [RFC-8288](https://tools.ietf.org/html/rfc8288)
schema:
type: string
current-page:
description: The current page number of the results. Page numbers start at 1.
schema:
type: integer
page-items:
description: The number of items per page of results.
schema:
type: integer
total-pages:
description: The total number of pages in the result set.
schema:
type: integer
total-count:
description: The total number of items (across all pages) in the result set.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesResponse'
example:
images:
- asset_id: ea9edd7e217cf2805a803c23c2517b68
url: 'https://s3.amazonaws.com/images/fruit-bowl.jpg'
alt_text: A bowl of apples with a banana on top.
alt_texts:
en: A bowl of apples with a banana on top.
created_at: 1662643276
errors: {}
error_code: null
- asset_id: fecafe3b59a4da414abf8c8c9ecd3f88
url: 'https://s3.amazonaws.com/images/banana.jpg'
alt_text: A ripe banana on a kitchen table.
alt_texts:
en: A ripe banana on a kitchen table.
created_at: 1692648874
errors: {}
error_code: null
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Details about the error encountered.
example:
error: "Search query was too long or invalid."
x-internal: false
/images/bulk_create:
post:
operationId: bulk-create
tags:
- Images
description: Upload and process a CSV of image URLs that need alt text. Valid rows will be processed, and invalid rows will be returned in the `row_errors` response field.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
contentMediaType: application/octet-stream
description: The CSV file to upload. Maximum of 100000 rows of data.
email:
type: string
description: "[optional] Email address for sending results of the bulk upload."
responses:
'200':
description: Successful addition of the image URL and alt text generation.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUpload'
example:
success: true
rows: 23
row_errors: [[2, "Invalid URL"]]
error: null
4XX:
description: CSV upload failed or was not processed. See error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUpload'
example:
success: false
rows: 0
error: Unable to process file
/images/page_scrape:
post:
operationId: page-scrape
tags:
- Images
description: |
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.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
page_scrape:
type: object
properties:
url:
type: string
description: URL of the page to be scraped. Can be null if you are only sending the `html` param.
html:
type: string
description: |
[optional] Raw HTML document to parse. Make sure to properly escape quoted strings, etc.
keywords:
type: array
maxItems: 6
items:
type: string
description: |
[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:
type: array
maxItems: 6
items:
type: string
description: |
[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:
type: string
default: en
description: |
The language(s) for the generated alt text. Use comma-separated language codes (e.g., `"en,es,fr"`). Use one of our [supported language codes](https://alttext.ai/support#faq-tech) 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:
type: boolean
default: false
description: |
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.
examples:
Scrape images from an HTML page:
value:
page_scrape:
url: 'https://www.image-blog.com/gallery.html'
Scrape a page and process all images including ones with alt text:
value:
page_scrape:
url: 'https://www.image-blog.com/gallery.html'
include_existing: true
Scrape images and generate alt text for each image using SEO keywords:
value:
page_scrape:
url: 'https://www.visit-hawaii.com/surfing.html'
keywords:
- Hawaii vacations
- big waves
- surfing
Scrape images and generate alt text in multiple languages:
value:
lang: "en,es"
page_scrape:
url: 'https://www.image-blog.com/gallery.html'
responses:
'200':
description: Successful addition of the image URL and alt text generation.
content:
application/json:
schema:
$ref: '#/components/schemas/PageScrapeResponse'
example:
url: 'https://www.image-blog.com/gallery.html'
total_processed: 2
errors: null
scraped_images:
- src: "https://www.image-blog.com/images/butterfly.jpg"
alt: null
width: 640
height: 480
skip_reason: null
- src: "https://www.image-blog.com/images/caterpillar.jpg"
alt: null
width: 640
height: 480
skip_reason: null
4XX:
description: The page scrape was not successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageScrapeResponse'
example:
url: 'https://www.image-blog.com/wrong.html'
total_processed: 0
errors:
base:
- Unable to download HTML
scraped_images:
webhooks:
imageEvent:
post:
operationId: ImageEvent
tags:
- Webhooks
description: |
Webhook for image events.
Webhooks are sent to the Notification URL you provide in [Account Settings](https://alttext.ai/account/edit).
There are two types of webhook events that are sent:
* `uploaded` - Sent when new images are added to the library.
* `deleted` - Sent when images are deleted from the library.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookPayload'
examples:
uploaded event:
value:
event: uploaded
schema_ver: 1.0.1
timestamp: 1663438241
data:
images:
- asset_id: ea9edd7e217cf2805a803c23c2517b68
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
alt_text: A monarch butterfly
alt_texts:
en: A monarch butterfly
es: Una mariposa monarca
tags:
- insect
- butterfly
metadata:
internal_id: 123
kingdom: Animalia
phylum: Arthopoda
class: Insecta
created_at: 1662643276
errors: {}
error_code: null
deleted event:
value:
event: deleted
schema_ver: 1.0.1
timestamp: 1663438241
data:
images:
- asset_id: ea9edd7e217cf2805a803c23c2517b68
url: 'https://upload.wikimedia.org/wikipedia/commons/6/63/Monarch_In_May.jpg'
alt_text: A monarch butterfly
alt_texts:
en: A monarch butterfly
tags:
- insect
- butterfly
metadata:
internal_id: 123
kingdom: Animalia
phylum: Arthopoda
class: Insecta
created_at: 1662643276
errors: {}
error_code: null
responses:
'200':
description: Indicates the webhook was received and will not be retried.