Automatic Image ALT Text

Automatic ALT text describes images in Core Files with a vision model, once per image, and translates that description into each site language. It runs in the background as the system actor, so it never spends a member's AI points. It is off by default.

import { resolveImageAlt } from '@vitnode/core/lib/files/resolve-alt'

;<img
  alt={
    resolveImageAlt({
      alts: item.coverImage.alts, // the file's ALT per language
      fallbackLocales: [defaultLocale],
      locale,
      occurrence: { alt: item.coverImageAlt }, // this article's own ALT
    }).alt
  }
  src={item.coverImage.url}
/>

Turn it onCopy Anchor Link

{
  id: 'default',
  name: 'GPT-4o Mini',
  model: openai('gpt-4o-mini'),
  capabilities: ['text', 'image-input', 'structured-output', 'streaming'], 
  pricing: { rates: { inputPerMillion: '0.15', outputPerMillion: '0.60' } },
}

How it worksCopy Anchor Link

1. Upload. A new JPEG, PNG, GIF or WebP in core_files is queued right away when the feature is on. A failure to queue never fails the upload.
2. Sweep. The ai-alt-detect cron (hourly) looks for images still missing ALT in a configured language and queues them.
3. Work. The ai-queue cron (every minute) takes up to 2 queued images and describes them.
4. Describe once. The image gets one base description in English, per file fingerprint.
5. Translate. Each missing language gets a translation of that base description. English uses it as-is.
6. Write. Each language goes to core_files_alt, but only if no person wrote it and the file is still the same version.
7. Notify. files.alt.updated is emitted with the languages that were written.

One description per image, translations per languageCopy Anchor Link

The base description is stored in core_files_alt_analysis, keyed by the file and its fingerprint (SHA-256 of the stored bytes). When you add a language later, the sweep notices the gap and only the translation runs. The image does not go back to the vision model.

When a file's bytes change, its fingerprint changes. AI texts written for the old fingerprint count as missing, so the image is described again. The file ALT API marks such texts as stale until then.

People always winCopy Anchor Link

The job never overwrites a row with origin: "human", whether on a new run, on a retry or after the file changes. That includes an empty human text: an empty string means "a person decided this image needs no description", which is different from no row at all.

To let the job write a language again, delete that language's ALT row.

Per-file policyCopy Anchor Link

Each file has an altPolicy:

The job checks the policy again at write time, so a policy changed mid-run still wins.

The sweepCopy Anchor Link

The sweep walks core_files in id order from a stored cursor, at most 200 files per run, and queues up to Images queued per sweep of them. When it reaches the end, it wraps to the start, so it revisits every image and finds any new language or missed upload.

Queuing is deduplicated: a file that is already pending or processing in the queue is not queued twice.

Budget waits are not failuresCopy Anchor Link

When the site budget, the background jobs budget or the global switch stops a run, the task is deferred, not failed. It goes back to pending without spending a retry, with the file's state set to waiting_budget. It wakes at the start of the next budget month or in one hour, whichever comes first. Raise the budget mid-month and work resumes within the hour.

Other failures (provider error, invalid output, timeout) use the normal queue retries: 3 attempts, then the file's state is failed. The next sweep wrap queues it again.

Its own queueCopy Anchor Link

ALT tasks run on a dedicated ai queue. The general process-queue worker skips it, and ai-queue processes it under its own lock with a batch of 2. A slow vision model never delays e-mails or other queue work.

Each task has a 15-minute lease. A worker that dies mid-task leaves it processing; once the lease expires it goes back to pending (the attempt is spent), or to failed when no attempts are left. The AI run it started is settled as uncertain by ai-maintenance and charged at its reservation.

Image bytes stay privateCopy Anchor Link

The job reads the image server-side and sends bytes to the provider, never a URL:

• through the storage adapter's optional read(key, { maxBytes }) method (the Local adapter has one);
• otherwise by a bounded server-side fetch() of the adapter's URL.

Files over 20 MB are skipped. With sharp installed, the copy sent to the provider is resized to at most 1024 px and re-encoded as WebP. A private file never has to be made public for the AI provider.

Render the ALT textCopy Anchor Link

For images that have ALT text, Content Engine file descriptors carry it as alts, a map of language code to text:

{
  id: 42,
  name: 'bike.jpg',
  url: 'https://example.com/uploads/bike.jpg',
  mimeType: 'image/jpeg',
  alts: { en: 'A red bicycle leaning on a brick wall', pl: 'Czerwony rower oparty o ceglaną ścianę' },
  // ...
}

resolveImageAlt() from @vitnode/core/lib/files/resolve-alt picks the text for one place the image appears, in this order:

The article's own ALT text always wins over the file's default. The blog's post page (plugins/blog/src/pages/post-page.tsx) is a complete example.

Running the cronCopy Anchor Link

ALT text depends on three cron jobs registered by @vitnode/core:

Registering a cron job does not run it. The host must call VitNode's cron endpoint, in one of two ways.

In-process. On a long-running server, register the Node CRON adapter. It calls the endpoint every minute:

import { NodeCronAdapter } from '@vitnode/node-cron'
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  cron: NodeCronAdapter(), 
  // ...
})

External scheduler. On serverless hosting nothing stays alive to hold a timer, so an external scheduler must call the endpoint, ideally once a minute:

curl -X POST https://example.com/api/@vitnode/core/cron \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CRON_SECRET"

Set a real CRON_SECRET. Each call runs every job whose schedule came due since its last run. A slower tick still runs the hourly sweep; it just works the queue less often (2 images per tick). Check Last Run at /admin/core/advanced/cron. See Cron over REST and Node CRON adapter.

Edit ALT text through the APICopy Anchor Link

The file ALT routes live in the admin/files module and use the files staff permissions:

await fetcher({
  plugin: '@vitnode/core',
  method: 'put',
  module: 'admin/files',
  path: '/{id}/alt',
  args: {
    params: { id: 42 },
    body: { languageCode: 'pl', text: 'Czerwony rower' },
  },
})

React to new ALT textCopy Anchor Link

files.alt.updated fires when the job (origin: "ai") or a person (origin: "human") writes a file's default ALT:

import { buildEventListener } from '@vitnode/core/api/lib/events'

export const altUpdatedListener = buildEventListener({
  event: 'files.alt.updated',
  name: 'refresh-gallery-alt',
  handler: async (c, { fileId, languageCodes, origin }) => {
    await c
      .get('log')
      .info(`ALT for file ${fileId} (${languageCodes.join(', ')}) by ${origin}`)
  },
})

See Built-in events.

Limits and gotchasCopy Anchor Link

• Images only. The job reads image/jpeg, image/png, image/gif and image/webp. It never analyses other files.
• Base language is English. Other languages are translations of the English description.
• Legacy metadata.alt is not migrated. An ALT a plugin stored in the free-form core_files.metadata column has no language, and VitNode does not guess one. The job treats those images as missing ALT text. Copy such values into core_files_alt yourself with PUT /admin/files/{id}/alt if you know their language.
• Cost. The Automatic ALT text card on Artificial Intelligence (AI) → Overview shows images described, translations and the known cost per image and per translation.

Learn moreCopy Anchor Link