Text Suggestions API 運用 Product Studio API 的生成式 AI 工具,生成及最佳化產品名稱和說明。這項功能可提升顧客參與度和轉換率,並簡化管理及更新產品資訊的程序。Product Studio API 的功能可協助你提升零售成效。
您可以使用 API 生成什麼內容?
Text Suggestions API 可協助您執行下列操作:
- 根據產品圖片和/或產品屬性,建議產品名稱和說明。
- 生成經過 SEO 最佳化的產品標題
- 自訂產品標題的格式
- 根據產品動態饋給生成產品說明
你也可以指定說明語氣,確保所有產品資訊風格一致。
快速入門導覽課程
GenerateProductTextSuggestions 方法可使用產品資訊生成或最佳化產品名稱和說明。
API 接受:
- 產品屬性 (JSON 字典):包含產品屬性 (例如
{"title": "White Tee", "brand": "MyBrand", "size": "XL"}) 的 JSON 物件 - 產品圖片:指向產品圖片的 URI (例如
{"uri": "https://my-store.com/img/1.png"}) - 標題格式選項:自訂標題生成的參數,包括:
attribute_separator:指定屬性之間的分隔符號。target_language::設定輸出語言。attribute_order:定義產生的名稱中屬性的順序。
- 資料標籤範例:查看如何根據說明生成標題的範例。
- 工作流程 ID (
output_spec.workflow_id):output_spec物件中的workflow_id欄位決定文字生成類型: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"
},
}
}
}
根據標題和說明 (以及自訂範例) 最佳化標題
在這個範例中,我們明確標示要 AI 識別的產品屬性,以及輸出內容中的屬性排序。
要求
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 回應中生成的說明文字語言。您可以在 output_spec 參數中加入 target_language:
{
"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": "カリフォルニアの黒いコーヒー豆は、あなたの鼻をくすぐる、甘く、フローラルな香りです。この香りは、コーヒー豆の豊かな香りと、ジャスミンとバラの繊細な花の香りをブレンドしたものです。カリフォルニアの黒いコーヒー豆は、あなたの家を居心地の良いカフェに変え、あなたをリラックスした気分にさせてくれるでしょう。この香りは、コーヒー好きにも、フローラルな香り好きにも最適です。カリフォルニアの黒いコーヒー豆で、あなたの家を幸せな香りで満たしましょう!."
},
}
生成說明時,可自訂語氣
你可以自訂生成說明的語氣,建立品牌形象,讓網路商店脫穎而出。Text API 提供兩種選項:
- 預先定義的語氣選項:您可以從語氣清單中選取,生成新的說明。清單包含下列語氣風格:
- 預設:簡單、清晰、優雅。
- 俏皮:輕鬆、使用正面語言、幽默 (笑話、雙關語) 和誇張 (不使用諷刺、嘲諷或表情符號)。
- 正式:標準英文、正確文法、完整句子,不使用俚語或縮寫。
- 具說服力:邏輯清晰、簡潔有力,且論點明確,能說服讀者。
- 對話式:親切、簡單易懂的日常用語。
- 品牌專屬語氣:您可以提供現有的說明或其他文字素材資源,並採用品牌語氣。生成式 AI 模型會分析文字語氣,並根據下列面向生成「寫作風格描述元」:
- 正式程度 (例如正式、非正式)
- 詳細程度 (例如精簡、非常詳細)
- 語氣 (例如專業、資訊豐富、正面、具說服力)
- 語句結構 (例如「簡單句,少有連接詞」)
- 最常使用的字詞和詞組
用戶端程式庫
建議您使用用戶端程式庫提交要求。我們會提供用戶端程式庫,您可以安裝在 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"
}
}
每個 title_example 都必須包含 (Something)
以下四個範例
{
"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_infocategorytitle_formatfinal_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:生成或最佳化產品名稱。
- description:生成或最佳化產品說明。
- 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 設為「cheerful」,但這個欄位僅支援下列其中一個值:
- default:簡單、清晰、優雅。
- playful:輕鬆、使用正面語言、幽默 (笑話、雙關語) 和誇飾 (不使用諷刺、反諷或表情符號)。
- formal:標準英文、正確文法、完整句子,不使用俚語或縮寫。
- 說服:邏輯清晰、簡潔有力,以論點說服讀者。
- 對話式:親切、簡單易懂的日常用語。