Auto-generate alt text for Media Library assets

import {defineAssetAspect, defineField, defineArrayMember} from 'sanity'

const languages = [
  {title: 'Dutch', value: 'nl'},
  {title: 'English', value: 'en'},
  {title: 'French', value: 'fr'},
  {title: 'German', value: 'de'},
]

export default defineAssetAspect({
  name: 'altText',
  title: 'Alternative text',
  description: 'Accessible alternative text for this asset, in one or more languages.',
  type: 'array',
  of: [
    defineArrayMember({
      name: 'altTextItem',
      type: 'object',
      fields: [
        defineField({
          name: 'language',
          type: 'string',
          description: 'The language that the alt text is written in',
          options: {
            list: languages,
            layout: 'radio',
          },
        }),
        defineField({
          name: 'value',
          title: 'Alternative text',
          type: 'string',
          description: 'Short description of the image, for screen readers (max ~100 characters).',
        }),
      ],
      preview: {
        select: {
          title: 'value',
          subtitle: 'language',
        },
      },
    }),
  ],
})

import {documentEventHandler} from '@sanity/functions'
import {createClient} from '@sanity/client'

const MAX_KEYWORD_WAIT = 5 // How many times to retry (total attempts = MAX_KEYWORD_WAIT + 1)
const KEYWORD_WAIT_MS = 1500 // Wait 1.5 seconds between checks
const languages = ['nl', 'en', 'fr', 'de']

// We have to wait for the keywords to be available because they are auto-generated by the Media Library when an image is uploaded.
async function waitForKeywords(
  fetchKeywords: () => Promise<string[] | undefined>,
): Promise<string[] | undefined> {
  for (let i = 0; i <= MAX_KEYWORD_WAIT; i++) {
    console.log('Waiting for keywords...', i)
    const keywords = await fetchKeywords()
    if (keywords && keywords.length > 0) {
      return keywords
    }
    if (i < MAX_KEYWORD_WAIT) {
      await new Promise((res) => setTimeout(res, KEYWORD_WAIT_MS))
    }
  }
  return undefined
}

export const handler = documentEventHandler(async ({context, event}) => {
  const mlId = context.eventResourceId
  const {_id, currentVersion} = event.data
  const detailedAssetId = currentVersion?._ref

  if (!detailedAssetId) {
    console.log('No detailedAssetId found, skipping')
    return
  }

  // Create a Media Library client
  const mediaLibraryClient = createClient({
    token: context.clientOptions.token,
    useCdn: false,
    apiVersion: '2025-05-08',
    resource: {
      type: 'media-library',
      id: mlId,
    },
  })

  // Query keywords from the Media Library asset using client.fetch()
  const fetchKeywords = async () => {
    try {
      const result = await mediaLibraryClient.fetch<{keywords?: string[]}>(
        `*[_id == $assetId][0]{ "keywords": metadata.keywords }`,
        {assetId: detailedAssetId},
      )
      return result?.keywords || []
    } catch (err) {
      console.error('Failed fetching keywords from asset', err)
      return []
    }
  }

  const keywords = await waitForKeywords(fetchKeywords)

  if (!keywords || keywords.length === 0) {
    console.log('No keywords found after retries, skipping')
    return
  }

  // Generate alt text based on the keywords using Agent Actions
  const agentClient = createClient({
    ...context.clientOptions,
    dataset: 'production',
    apiVersion: 'vX',
  })

  // Generate alt text for each language separately for reliability
  const altTextItemsArray: {_key: string; _type: string; language: string; value: string}[] = []

  for (const lang of languages) {
    const altText = await agentClient.agent.action.prompt({
      instruction: `Given the following keywords: [${keywords.join(', ')}], generate a short (max 100 chars) alt text in language: ${lang}. Respond with just the alt text string, no quotes or formatting.`,
    })

    altTextItemsArray.push({
      _key: crypto.randomUUID(),
      _type: 'altTextItem',
      language: lang,
      value: String(altText).trim(),
    })
  }

  // Update the asset with the alt text using the Media Library client
  const result = await mediaLibraryClient
    .patch(_id)
    .setIfMissing({aspects: {}})
    .set({'aspects.altText': altTextItemsArray})
    .commit()

  console.log('Mutation response:', JSON.stringify(result, null, 2))
})

import {defineBlueprint, defineMediaLibraryAssetFunction} from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineMediaLibraryAssetFunction({
      name: 'media-library-auto-alt-text',
      memory: 2,
      timeout: 30,
      src: './functions/media-library-auto-alt-text',
      event: {
        on: ['create', 'update'],
        filter: 'assetType == "sanity.imageAsset" && !defined(aspects.altText)',
        projection: '{ _id, currentVersion }',
        resource: {
          type: 'media-library',
          id: '<your-media-library-id>', // TODO: replace with your media library id
        },
      },
    }),
  ],
})