API текстовых подсказок использует инструменты генеративного искусственного интеллекта API Product Studio для создания и оптимизации заголовков и описаний товаров. Вы можете использовать его для повышения вовлеченности клиентов и конверсии, а также для упрощения процесса управления и обновления информации о товарах. Функции API Product Studio помогут вам оптимизировать показатели розничной торговли.
Что можно сгенерировать с помощью API?
API текстовых подсказок позволяет выполнять следующие действия:
- Предложенные названия и описания товаров на основе изображения товара и/или его характеристик.
- SEO-оптимизированные заголовки для ваших товаров
- Заголовки для ваших товаров, отформатированные по вашему желанию.
- Описания товаров из вашего товарного фида
Вы также можете задать тон описаниям и обеспечить единообразие во всех описаниях товаров.
Быстрый старт
Метод GenerateProductTextSuggestions позволяет генерировать или оптимизировать заголовки и описания товаров, используя информацию о ваших товарах.
API принимает следующие данные:
- Атрибуты товара (словарь JSON): объект JSON, содержащий атрибуты товара (например,
{"title": "White Tee", "brand": "MyBrand", "size": "XL"}). - Изображение товара: URI, указывающий на изображение товара (например,
{"uri": "https://my-store.com/img/1.png"}). - Параметры форматирования заголовка : Параметры для настройки генерации заголовка, включая:
-
attribute_separator: Указывает разделитель между атрибутами. -
target_language: Задает язык вывода. -
attribute_order: Определяет порядок атрибутов в сгенерированном заголовке.
-
- Примеры разметки данных : см. пример того, как сгенерировать заголовок из описания .
- Идентификатор рабочего процесса (
output_spec.workflow_id) : Полеworkflow_idв объектеoutput_specопределяет тип генерации текста:-
title: Генерирует или оптимизирует название продукта. -
description: Генерирует или оптимизирует описание продукта. -
tide: Генерирует или оптимизирует как заголовок, так и описание товара.
-
Примеры
Ниже приведены примеры использования API для генерации или оптимизации заголовка или описания, или и того и другого, на основе различных входных данных о продукте. Мы также представляем распространенные ошибки и проблемы, а также способы их решения.
Оптимизированная генерация заголовков
В примере показано, как сгенерировать оптимальный заголовок.
Запрос
В теле запроса содержится информация о продукте, используемая для оптимизации заголовка. Вот пример структуры запроса:
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"title": "Nike Mens shoes",
"description": "Give strength to your step with the Nike Air Zoom Pegasus 38 shoe for Men with shoe size 12. Ensuring the fit is loved by the runners. This shoes comes in Blue color.",
"brand": "Nike"
}
},
"output_spec": {
"workflow_id": "title"
}
}
Ответ
Вы можете ожидать ответа примерно такого содержания:
{
"title": {
"text": "Nike Mens shoes Air Zoom Pegasus 38 Running Shoes, Blue, Size 12"
},
"metadata": {
"metadata": {
"attributes": {
"color": "Blue",
"size": "12",
"product": "Running shoes",
"model": "Air Zoom Pegasus 38"
},
}
}
}
Создать заголовок, используя только изображение.
В примере показано, как добавить изображение товара и сгенерировать оптимальный заголовок.
Запрос
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_image":{
"uri": "https://cdn.shopify.com/s/files/1/0653/5879/0892/products/1672082339438_550x825.jpg?v=1672082415"
}
},
"output_spec": {
"workflow_id": "title",
"attribute_separator": "-"
}
}
Ответ
{
"title": {
"text": "Rustic Ceramic & Leather Leaves Necklace"
},
"metadata": {
"metadata": {
"attributes": {
"material": "Rustic Ceramic & Leather",
"pattern": "Leaves",
"product": "Necklace"
},
}
}
}
Сгенерировать заголовок на основе описания
В примере показано, как составить описание товара и сгенерировать оптимальный заголовок.
Запрос
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"description": "selling size 12 nike dunks. oh they are red by the way!"
}
},
"output_spec": {
"workflow_id": "title",
}
}
Ответ
{
"title": {
"text": "Nike Dunks Red Size 12"
},
"metadata": {
"metadata": {
"attributes": {
"brand": "Nike",
"color": "Red",
"size": "12",
"product": "Dunks"
},
}
}
}
Оптимизация заголовков на основе заголовка и описания (с использованием пользовательского примера).
В этом примере мы явно указываем атрибуты продукта, которые хотим, чтобы ИИ идентифицировал, а также порядок атрибутов в выходных данных.
Запрос
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"title": "Volumizing & Lengthening Mascara - Dark Brown",
"description": "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging.",
"brand": "Luxe Beauty"
}
},
"output_spec": {
"workflow_id": "title"
}
"title_examples": [
{
"product_info": {
"title": "Lash Paradise Volumizing & Lengthening Mascara - Waterproof - Blackest Black",
"colour": "Black"
},
"title_format": "product",
"category": "mascara",
"final_product_info": {
"product": "Mascara",
"brand": "Lash Paradise",
"mascara_type": "Volumizing & Lengthening",
"colour": "Blackest Black",
"waterproof": "Waterproof",
}
},
{
"product_info": {
"title": "Hypnose Drama Instant Full Body Volume Mascara - Black",
"colour": "Black"
},
"title_format": "product",
"category": "mascara",
"final_product_info": {
"product": "Mascara",
"brand": "Hypnose",
"sub_brand": "Drama",
"mascara_type": "Full Body Volume",
"colour": "Black",
"eye_lash_type": "All lash types"
}
}
]
}
Ответ
{
"title": {
"text": "Luxe Beauty Dark Brown Volumizing & Lengthening Mascara"
},
"metadata": {
"metadata": {
"attributes": {
"brand": "Luxe Beauty",
"colour": "Dark Brown",
"mascara_type": "Volumizing & Lengthening",
"product": "Mascara"
},
}
}
}
Сгенерировать описание на основе заголовка
В примере показано, как указать название товара и запросить у API генерацию соответствующего описания товара.
Запрос
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"title": "Rustic Ceramic & Leather Leaves Necklace",
}
},
"output_spec": {
"workflow_id": "description"
}
}
Ответ
{
"description": {
"text": "Rustic Ceramic & Leather Leaves Necklace is a beautiful necklace made from high-quality ceramic and leather. It features a unique design that is sure to turn heads.
"
},
}
Сгенерируйте заголовок и описание на основе атрибутов товара (таких как бренд и цвет).
В этом примере показано, как указать атрибуты продукта для создания оптимального названия и описания продукта.
Запрос
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"brand": "Mr. Beast",
"color": "purple",
},
"product_image":{
"uri": "https://mrbeast.store/cdn/shop/files/0015dlv_0000_327.jpg?v=1702754475&width=500"
}
},
"output_spec": {
"workflow_id": "description"
}
}
Ответ
{
"title": {
"text": "Pajamas - Mr. Beast | Purple"
},
"description": {
"text": "Slip into the ultimate comfort and style with these Mr. Beast pajamas in a vibrant shade of purple. Crafted from the softest materials, these pajamas will envelop you in a cozy embrace, ensuring a restful night's sleep. The shorts feature a relaxed fit, allowing for easy movement, while the top boasts a classic design with a comfortable neckline. Whether you're lounging at home or drifting off to dreamland, these Mr. Beast pajamas are the perfect choice for a peaceful and stylish slumber."
},
}
Поддержка целевого языка
В этом поле указывается язык описания, генерируемого в ответе API. Вы можете добавить target_language в качестве части параметров output_spec :
{
"output_spec": {
"target_language": "language"
}
}
Примеры значений:
"korean" (Korean)
"english" (English)
"spanish" (Spanish)
"french" (French)
Пример запроса
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"title": "Granos de café negro",
"description": "Los granos de café negro en California",
"brand": "Parfums de Paris",
"scent": "Floral",
},
"product_image":{
"uri": "https://mrbeast.store/cdn/shop/files/0015dlv_0000_327.jpg?v=1702754475&width=500"
}
},
"output_spec": {
"workflow_id": "description",
"target_language": "japanese",
"attribute_order": ["scent", "product"],
"tone": "playful",
}
}
Ответ
{
"description": {
"text": "カリフォルニアの黒いコーヒー豆は、あなたの鼻をくすぐる、甘く、フローラルな香りです。この香りは、コーヒー豆の豊かな香りと、ジャスミンとバラの繊細な花の香りをブレンドしたものです。カリフォルニアの黒いコーヒー豆は、あなたの家を居心地の良いカフェに変え、あなたをリラックスした気分にさせてくれるでしょう。この香りは、コーヒー好きにも、フローラルな香り好きにも最適です。カリフォルニアの黒いコーヒー豆で、あなたの家を幸せな香りで満たしましょう!."
},
}
Персонализация тональности голоса для генерации описаний.
Чтобы укрепить свой бренд и выделить свой интернет-магазин среди конкурентов, вы можете персонализировать тон генерируемых описаний. API для работы с текстом предлагает два варианта:
- Выбор предустановленного тона: Вы можете выбрать тон из списка для создания новых описаний. Список включает следующие стили тона:
- По умолчанию: Простой, понятный и элегантный.
- Игривый: Беззаботный, с использованием позитивного языка, юмора (шутки, каламбуры) и преувеличения (без иронии, сарказма или смайликов).
- Формальный стиль: стандартный английский, правильная грамматика, полные предложения, без сленга и сокращений.
- Убедительный: Логичный, лаконичный и основанный на аргументах, призванный убедить читателя.
- Разговорный стиль: дружелюбный, простой для понимания, повседневный язык.
- Фирменный стиль: Вы можете использовать существующие описания или другие текстовые материалы, выдержанные в фирменном стиле вашего бренда. Модель генеративного ИИ проанализирует тон текста и сгенерирует «дескриптор стиля письма» на основе следующих аспектов:
- Формальность (например, формальный, неформальный)
- Многословность (например, краткость, излишняя многословность)
- Тон (например, профессиональный, информативный, позитивный, убедительный)
- Структура предложения (например, «простое предложение с небольшим количеством союзов»)
- Наиболее часто используемые слова и фразы
Клиентские библиотеки
Мы рекомендуем использовать клиентские библиотеки для отправки запросов. Мы предоставим вам эти библиотеки, которые вы сможете установить в свой проект Maven.
Примеры кода
Выберите способ аутентификации и настройте эти примеры кода, следуя инструкциям . Вот пример, который можно использовать для генерации текстовых подсказок.
Java
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.productstudio.v1alpha.GenerateProductTextSuggestionsRequest;
import com.google.shopping.merchant.productstudio.v1alpha.GenerateProductTextSuggestionsResponse;
import com.google.shopping.merchant.productstudio.v1alpha.OutputSpec;
import com.google.shopping.merchant.productstudio.v1alpha.ProductInfo;
import com.google.shopping.merchant.productstudio.v1alpha.TextSuggestionsServiceClient;
import com.google.shopping.merchant.productstudio.v1alpha.TextSuggestionsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to generate product text suggestions. */
public class GenerateProductTextSuggestionsSample {
private static String getName(String accountId) {
return String.format("accounts/%s", accountId);
}
public static void generateProductTextSuggestions(Config config) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
TextSuggestionsServiceSettings textSuggestionsServiceSettings =
TextSuggestionsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
String name = getName(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (TextSuggestionsServiceClient textSuggestionsServiceClient =
TextSuggestionsServiceClient.create(textSuggestionsServiceSettings)) {
ProductInfo productInfo =
ProductInfo.newBuilder()
.putProductAttributes("title", "Mens shirt")
.putProductAttributes("description", "A blue shirt for men in size S")
.build();
OutputSpec outputSpec = OutputSpec.newBuilder().setWorkflowId("title").build();
GenerateProductTextSuggestionsRequest request =
GenerateProductTextSuggestionsRequest.newBuilder()
.setName(name)
.setProductInfo(productInfo)
.setOutputSpec(outputSpec)
.build();
System.out.println("Sending GenerateProductTextSuggestions request: " + name);
GenerateProductTextSuggestionsResponse response =
textSuggestionsServiceClient.generateProductTextSuggestions(request);
System.out.println("Generated product text suggestions response below:");
System.out.println(response);
} catch (Exception e) {
System.out.println("An error has occured: ");
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
generateProductTextSuggestions(config);
}
}
Python
"""A module to generate product text suggestions."""
from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_productstudio_v1alpha import GenerateProductTextSuggestionsRequest
from google.shopping.merchant_productstudio_v1alpha import OutputSpec
from google.shopping.merchant_productstudio_v1alpha import ProductInfo
from google.shopping.merchant_productstudio_v1alpha import TextSuggestionsServiceClient
# Fetches the Merchant Center account ID from the configuration file.
# This ID is used to construct the 'name' for the API request.
_ACCOUNT_ID = configuration.Configuration().read_merchant_info()
# The parent resource name for the GenerateProductTextSuggestionsRequest.
# Format: "accounts/{account}"
_PARENT_RESOURCE_NAME = f"accounts/{_ACCOUNT_ID}"
def generate_product_text_suggestions_sample():
"""Generates product text suggestions for a given product."""
# Gets OAuth Credentials.
credentials = generate_user_credentials.main()
# Creates a client for the TextSuggestionsService.
client = TextSuggestionsServiceClient(credentials=credentials)
# Defines the product information for which suggestions are needed.
# This includes attributes like title and description.
product_info = ProductInfo(
product_attributes={
"title": "Mens shirt",
"description": "A blue shirt for men in size S",
}
)
# Defines the output specification.
# The 'workflow_id' specifies the type of text suggestion, e.g., "title".
output_spec = OutputSpec(workflow_id="title")
# Creates the request object for generating product text suggestions.
# It includes the parent resource name, product information, and output
# specification.
request = GenerateProductTextSuggestionsRequest(
name=_PARENT_RESOURCE_NAME,
product_info=product_info,
output_spec=output_spec,
)
# Sends the request to the API.
print(
f"Sending GenerateProductTextSuggestions request: {_PARENT_RESOURCE_NAME}"
)
try:
response = client.generate_product_text_suggestions(request=request)
# Prints the generated suggestions.
print("Generated product text suggestions response below:")
print(response)
except RuntimeError as e:
# Catches and prints any errors that occur during the API call.
print("An error has occured: ")
print(e)
if __name__ == "__main__":
generate_product_text_suggestions_sample()
Распространенные ошибки и проблемы
Вот несколько распространенных ошибок и способы их решения.
Для генерации текстовых подсказок необходима информация о товаре.
Если вы получили следующее сообщение об ошибке
Error message:
"error": {
"code": 400,
"message": "[product_info] Product info is required to generate text suggestions.",
"status": "INVALID_ARGUMENT",
...
}
Добавьте product_info в тело запроса и корректно заполните хотя бы один из product_attributes или product_image .
Например, отправка этого сообщения приведет к ошибке.
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"output_spec": {
"workflow_id": "title"
}
}
Для генерации текстовых подсказок необходимо наличие хотя бы одного поля в поле product_info.
Эта ошибка
{
"error": {
"code": 400,
"message": "[product_info.product_attributes] At least one field of product_info is required to generate text suggestions.",
"status": "INVALID_ARGUMENT",
...
}
Это означает, что вам необходимо включить как минимум одно поле product_info в тело запроса.
Например, публикация этого сообщения приведет к ошибке.
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
},
"output_spec": {
"workflow_id": "title"
}
}
Вместо этого используйте что-нибудь вроде
"product_info": {
"product_attributes": {
"description": "Selling size 12 Nike dunks. Oh they are red by the way!"
}
}
или
"product_info": {
"product_image":{
"uri": "https://cdn.shopify.com/s/files/1/0653/5879/0892/products/1672082339438_550x825.jpg?v=1672082415"
}
}
(Что-то) требуется в каждом примере заголовка
Ошибки, подобные приведенным ниже четырем примерам.
{
"error": {
"code": 400,
"message": "[title_examples.product_info] At least one field of product_info is required in each title_example.",
"status": "INVALID_ARGUMENT",
...
}
или
{
...
"message": "[title_examples.category] Category is required in each title_example.",
...
}
или
{
...
"message": "[title_examples.title_format] Title format is required in each title_example.",
...
}
или
{
...
"message": "[title_examples.final_product_info] At least one field of final_product_info is required in each title_example.",
...
}
укажите, что вы не заполнили обязательное подполе.
Например, следующий запрос вызовет ошибку.
POST
https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"description": "selling size 12 nike dunks. oh they are red by the way!"
}
},
"output_spec": {
"workflow_id": "title"
},
"title_examples": []
}
Для решения этой проблемы для каждого поля title_example, указанного в запросе, заполните все следующие подполя:
-
product_info -
category -
title_format -
final_product_info
Вот работающий пример:
{
"product_info": {
"product_attributes": {
"title": "Volumizing & Lengthening Mascara - Dark Brown",
"description": "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging.",
}
},
"output_spec": {
"workflow_id": "title"
},
"title_examples": [
{
"product_info": {
"title": "Lash Paradise Volumizing & Lengthening Mascara - Waterproof - Blackest Black",
"colour": "Black"
},
"title_format": "product",
"category": "mascara",
"final_product_info": {
"product": "Mascara",
"brand": "Lash Paradise",
"mascara_type": "Volumizing & Lengthening",
"colour": "Blackest Black",
"waterproof": "Waterproof",
}
}
]
}
Неподдерживаемый workflow_id
Этот тип ошибки
{
"error": {
"code": 400,
"message": "[\u003ceye3 title='/ProductStudioTextGenerationService.GenerateProductText, INVALID_ARGUMENT'/\u003e APPLICATION_ERROR; ... ;Unsupported workflow_id: attributes. Supported workflows are: [\"title\", \"description\", \"tide\"];AppErrorCode=3;StartTimeMs=1740696804045;unknown;ResFormat=uncompressed;ServerTimeSec=0.005976589;LogBytes=256;Non-FailFast;EffSecLevel=none;ReqFormat=uncompressed;ReqID=4d1786f59faa3ea7;GlobalID=0;Server=[2002:a05:6e16:618:b0:2c2:7cfc:bebd]:14001] Invalid value",
"status": "INVALID_ARGUMENT",
...
}
результатом такого запроса
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"title": "Volumizing & Lengthening Mascara - Dark Brown",
"description": "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging.",
},
"output_spec": {
"workflow_id": "attributes"
}
}
В запросе поле workflow_id устанавливается в значение "attributes", но это поле поддерживает только одно из следующих значений:
- title : Генерирует или оптимизирует название продукта.
- Описание : Генерирует или оптимизирует описание продукта.
- tide : Генерирует или оптимизирует как заголовок, так и описание товара.
Неподдерживаемый тон
Ошибка "Неподдерживаемый тон", например:
{
"error": {
"code": 400,
"message": "[\u003ceye3 title='/ProductStudioTextGenerationService.GenerateProductText, INVALID_ARGUMENT'/\u003e APPLICATION_ERROR; ... ; Unsupported tone: 'asdf'. Supported tones are: [\"default\", \"playful\", \"formal\", \"persuasive\", \"conversational\"];AppErrorCode=3;StartTimeMs=1740697325058;unknown;ResFormat=uncompressed;ServerTimeSec=7.45346E-4;LogBytes=256;Non-FailFast;EffSecLevel=none;ReqFormat=uncompressed;ReqID=f7d9bbbc73a1d342;GlobalID=0;Server=[2002:a05:6918:3486:b0:2bc:ccd4:79e6]:14001] Invalid value",
"status": "INVALID_ARGUMENT",
...
}
результатом такого запроса, как
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
"product_attributes": {
"title": "Volumizing & Lengthening Mascara - Dark Brown",
"description": "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging.",
},
"output_spec": {
"workflow_id": "description"
"tone": "cheerful"
}
}
Обратите внимание, что tone устанавливается на «веселый», но это поле поддерживает только одно из следующих значений:
- По умолчанию : Простой, понятный и элегантный.
- Игривый : Беззаботный, с использованием позитивного языка, юмора (шутки, каламбуры) и преувеличения (без иронии, сарказма или смайликов).
- Формальный стиль : стандартный английский, правильная грамматика, полные предложения, без сленга и сокращений.
- Убедительный : Логичный, лаконичный и основанный на аргументах, призванный убедить читателя.
- Разговорный : Дружелюбный, простой для понимания, повседневный язык.