Медиа, поиск по изображению и эмбеддинги

Операции группы media помещают изображения в то же векторное пространство, что и текст: вы загружаете изображение, платформа пишет в поле документа многоязычный эмбеддинг, и покупатель может искать по фото или по смыслу вместо ключевых слов. createEmbeddings эмбеддит обычный текст той же моделью — для всего, что вы хотите сравнивать с этими векторами самостоятельно.

Загрузка и управление объектами требуют полного ключа. searchByImage и searchSemantic — операции поисковой области, поэтому витрина вызывает их поисковым ключом, как любой другой поиск (см. ключи и области доступа). Каждый вызов эмбеддинга оплачивается из кошелька кредитов — см. кредиты.

Загрузка изображения

Небольшие изображения загружаются напрямую через uploadMedia — POST /media, multipart form data:

curl -X POST https://api.aacsearch.com/v1/media \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" \
  -F "file=@drill.jpg" \
  -F "collection=products" -F "document_id=42" -F "vector_field=image_embedding"

Для файла, который не помещается в один multipart-запрос, начните загрузку отдельно:

const upload = await client.media.createMediaUpload({
  mime: "image/jpeg",
  collection: "products",
  document_id: "42",
  vector_field: "image_embedding",
});
// upload.media_id — затем передайте байты:

curl -X PUT "https://api.aacsearch.com/v1/media/$MEDIA_ID/content" \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: image/jpeg" \
  -H "Content-Length: $(stat -c%s drill.jpg)" \
  --data-binary @drill.jpg

createMediaUpload (POST /media/uploads) резервирует объект (uploaded: false); putMediaContent передаёт его байты и требует Content-Length (411 без него, 413 свыше 100 МБ — см. ошибки). Эмбеддинг, а если запрошено — и описание, вычисляются, как только байты получены.

Чтение и удаление объекта

const asset = await client.media.getMedia({ mediaId });
// { media_id, mime, bytes, uploaded, caption, embedding, collection, document_id, vector_field, created_at }

await client.media.deleteMedia({ mediaId });

getMediaContent (GET /media/{mediaId}/content) отдаёт исходные байты. createMediaSignedUrl (POST /media/{mediaId}/signed_url) возвращает ограниченный по времени url и expires_at — чтобы передать изображение туда, где нельзя отправить ваш API-ключ: в шаблон письма, стороннему краулеру.

Поиск по изображению или по смыслу

Когда документы несут эмбеддинг, поиск больше не ограничен ключевыми словами:

curl -X POST https://api.aacsearch.com/v1/collections/products/documents/search/by_image \
  -H "X-NOVA-API-KEY: $NOVA_SEARCH_KEY" -F "file=@shopper-photo.jpg" -F "vector_field=image_embedding" -F "k=10"

Оба вызова возвращают хиты в том же формате, что и searchCollection. Используйте searchByImage, когда у покупателя есть фото — своё или из вашего каталога, — а searchSemantic, когда он описывает желаемое словами, но поиск по ключевым словам ничего близкого не находит. К любому из них можно добавить filter_by, как к обычному поиску.

Эмбеддинг текста напрямую

createEmbeddings — POST /embeddings — эмбеддит до 100 текстов (примерно по 500 токенов каждый) той же моделью, что и изображения, — так запрос и описание товара оказываются в одном сравнимом пространстве:

const { model, num_dim, data } = await client.embeddings.createEmbeddings({
  input: ["аккумуляторная дрель", "шуруповёрт"],
});
// data[0].length === num_dim

Используйте этот вызов, когда нужны сами векторы: сравнить их самостоятельно, сохранить вне AACSearch или построить собственный сигнал ранжирования — а не искать по коллекции напрямую.