> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to AltText AI

The AltText AI connector lets your AI agent act in each user's AltText AI account. Each user connects their own AltText AI API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 9 tools.

**Authentication:** API Key
**Categories:** AI, Marketing
**Tools:** 9: 4 read, 4 write, 1 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=ALTTEXTAI)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the AltText AI connection

   In **AgentKit > Connections**, create an AltText AI connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'alttextai'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize AltText AI:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'alttextai_account_get',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "alttextai"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize AltText AI:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="alttextai_account_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their AltText AI credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'alttextai_account_get',
  toolInput: {},
  connector: 'alttextai',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="alttextai_account_get",
    tool_input={},
    connection_name="alttextai",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `alttextai_account_get`

Get Account · Read-only

Get the AltText.ai account the API key belongs to.
Returns the account name, webhook URL, notification email, credit usage and subscription, and details of the calling key.
Use this to check remaining credits or to confirm the connection works.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `alttextai_image_get`

Get Image · Read-only

Get one image from the AltText.ai library.
Returns the image's asset_id, url, alt_texts by language, tags, metadata and timestamps.
Use alttextai_images_list or alttextai_images_search to find the asset ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `asset_id` (`string`, required): Asset ID of the image, from alttextai_images_list or the response of alttextai_image_create. Example: img-8f2a1c.

Example input: `{"asset_id":"<asset_id>"}`

### `alttextai_images_list`

List Images · Read-only

List the images in the AltText.ai library, one page at a time.
Returns each image's asset_id, url, alt_texts by language, tags and metadata, plus pagination details.
Use this to browse the library or to find one image by its exact URL. Use alttextai_images_search for a text, asset ID or partial URL search.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Number of results per page, at most 100. Example: 20.
- `page` (`integer`, optional): Page of results to return, starting at 1. Example: 1.
- `url` (`string`, optional): Only return the image with exactly this URL (no wildcards). Example: https://example.com/images/shoe.jpg.

Example input: `{}`

### `alttextai_images_search`

Search Images · Read-only

Search the AltText.ai library by alt text words, asset ID or URL substring; the search type is detected from the query.
Returns matching images with asset_id, url and alt_texts, plus pagination details.
Use this to find images when you do not know the exact URL. Use alttextai_images_list to page through everything.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `q` (`string`, required): Search query: words or a phrase from the alt text, an asset ID, or a URL fragment starting with http:// or https://. Example: red running shoe.
- `limit` (`integer`, optional): Number of results per page, at most 100. Example: 20.
- `page` (`integer`, optional): Page of results to return, starting at 1. Example: 1.

Example input: `{"q":"<q>"}`

### `alttextai_account_update`

Update Account · Write

Update the AltText.ai account's name, default webhook URL or notification email.
Returns the updated account.
Only the fields you set are sent.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `name` (`string`, optional): New account name. Example: Acme Store.
- `notification_email` (`string`, optional): Email address for important account notices such as a low credit balance. Example: ops@example.com.
- `webhook_url` (`string`, optional): Default URL that receives webhook notifications, for example when an async image finishes. Example: https://example.com/hooks/alttext.

Example input: `{}`

### `alttextai_image_create`

Generate Alt Text for Image · Write

Add an image to the AltText.ai library by public URL or base64 data and generate its alt text. Uses credits, except when the URL is already in the library.
Returns the image with its generated alt_texts by language (empty when async is true).
Use this for one image. Use alttextai_page_scrape to process every image on a web page. Send either url or raw, not both.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `asset_id` (`string`, optional): Your own unique ID for the image. Cannot contain ? & # \ / % < > +. Generated when omitted. Example: sku-1042-front.
- `async` (`boolean`, optional): true adds the image in the background and returns an empty body right away; use webhooks to learn when it is done. Not supported with raw. Example: false.
- `ecomm_brand` (`string`, optional): Brand of the product in the image; used with ecomm_product. Example: Acme.
- `ecomm_color` (`string`, optional): Color of the product in the image; used with ecomm_product. Example: red.
- `ecomm_product` (`string`, optional): Product name, to use the e-commerce vision model that includes product details in the alt text. Example: Trail Runner 2.
- `gpt_prompt` (`string`, optional): Final Pass prompt run on the generated alt text, in English. It must contain the AltText macro (the word AltText inside two pairs of curly braces), which is replaced with the generated alt text. Example: Rewrite this in under 100 characters: {{AltText}}
- `keyword_source` (`string`, optional): Text to take keywords from, such as a product description; only used when keywords is empty. Example: Lightweight trail running shoe with a grippy sole.
- `keywords` (`array`, optional): Keywords or phrases to consider when writing the alt text, for SEO; usually one or two of them are used. Example: ["running shoes", "trail"]
- `lang` (`string`, optional): Language code(s) for the generated alt text, comma-separated (for example en or en,es,fr). Each language after the first uses one extra translation credit per image. Defaults to the account's default language. Example: en,es.
- `max_chars` (`integer`, optional): Maximum length of the alt text. Defaults to the account setting. Example: 125.
- `metadata` (`object`, optional): Custom key-value data stored with the image and returned on every API response and webhook. Example: {"product_id": "1042"}
- `model_name` (`string`, optional): Writing style model: describe-detailed, describe-regular, describe-factual, succinct-describe-factual or describe-terse. Defaults to the account setting. Example: describe-regular. One of: `describe-detailed`, `describe-regular`, `describe-factual`, `succinct-describe-factual`, `describe-terse`.
- `negative_keywords` (`array`, optional): Words or phrases to remove from any generated alt text. Must be in English, even when lang asks for another language. Example: ["cheap"]
- `overwrite` (`boolean`, optional): true regenerates the alt text when an image with the same URL or asset ID already exists, using credits again. Example: false.
- `raw` (`string`, optional): Base64-encoded image data (RFC 4648, no line feeds), for images that are not publicly reachable. Send this or url. Not supported with async. Example: iVBORw0KGgoAAAANSUhEUgAA...
- `tags` (`array`, optional): Words or phrases to associate with the image. Example: ["shoes", "summer"]
- `timeout_secs` (`integer`, optional): Maximum seconds to wait for the alt text. Best left unset. Example: 30.
- `url` (`string`, optional): Public URL of the image (JPEG, PNG, GIF, WEBP or BMP, up to 16 MB). Send this or raw. Example: https://example.com/images/shoe.jpg.
- `webhook_url` (`string`, optional): Webhook URL for this request only, instead of the account default. Example: https://example.com/hooks/alttext.

Example input: `{}`

### `alttextai_image_update`

Update Image · Write

Update an image's alt text, asset ID or metadata in the AltText.ai library. The image URL cannot be changed.
Returns the updated image.
Use this to correct alt text by hand. Use alttextai_image_create with overwrite=true to regenerate it instead.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `asset_id` (`string`, required): Current asset ID of the image to update, from alttextai_images_list. Example: img-8f2a1c.
- `alt_text` (`string`, optional): New alt text for the image. Example: Red trail running shoe with a thick grippy sole.
- `lang` (`string`, optional): Language code(s) that alt_text is written in, comma-separated, for example en. Defaults to the account's default language. Example: en.
- `metadata` (`object`, optional): Custom key-value data to store with the image. Example: {"product_id": "1042"}
- `new_asset_id` (`string`, optional): New asset ID for the image; must be unique and cannot contain ? & # \ / % < > +. Example: sku-1042-side.
- `overwrite` (`boolean`, optional): true replaces existing alt text in those languages; false (default) keeps it. Example: true.

Example input: `{"asset_id":"<asset_id>"}`

### `alttextai_page_scrape`

Scrape Page Images · Write

Scan a web page (or an HTML document you send) for img elements and queue alt text generation for each image in the background. Uses credits per image.
Returns the images found on the page, without the final alt text; fetch it later with alttextai_image_get or alttextai_images_list.
Use this for a whole page. Use alttextai_image_create for one image. JavaScript is not run, and the page must load within 3 seconds.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `html` (`string`, optional): Raw HTML document to scan instead of fetching url. Example: <html><body><img src="https://example.com/a.jpg"></body></html>.
- `include_existing` (`boolean`, optional): true also processes images that already have alt text in the HTML; by default they are skipped. Example: false.
- `keywords` (`array`, optional): Keywords or phrases to consider when writing the alt text, for SEO; usually one or two of them are used. Example: ["running shoes", "trail"]
- `lang` (`string`, optional): Language code(s) for the generated alt text, comma-separated (for example en or en,es,fr). Each language after the first uses one extra translation credit per image. Defaults to the account's default language. Example: en.
- `negative_keywords` (`array`, optional): Words or phrases to remove from any generated alt text. Must be in English, even when lang asks for another language. Example: ["cheap"]
- `url` (`string`, optional): URL of the page to scan. Send this, html, or both. Example: https://example.com/products/trail-runner.

Example input: `{}`

### `alttextai_image_delete`

Delete Image · Destructive

Delete an image and its alt text from the AltText.ai library.
Returns an empty success response.
This cannot be undone.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `asset_id` (`string`, required): Asset ID of the image to delete, from alttextai_images_list. Example: img-8f2a1c.

Example input: `{"asset_id":"<asset_id>"}`

## Related

Other AI connectors ([all 216](/agentkit/connectors/?category=ai)):

- [Chorus](/agentkit/connectors/chorus/): Scalekit connector, Username and password, 9 tools
- [Gong](/agentkit/connectors/gong/): Scalekit connector, OAuth, 69 tools
- [Jiminny](/agentkit/connectors/jiminny/): Scalekit connector, Access token, 27 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
