Text Suggestions API, ürün başlıklarını ve açıklamalarını oluşturup optimize etmek için Product Studio API'nin üretken yapay zeka araçlarından yararlanır. Bu aracı kullanarak müşteri etkileşimini ve dönüşümü artırabilir, ürün bilgilerini yönetme ve güncelleme sürecini kolaylaştırabilirsiniz. Product Studio API'nin özellikleri, perakende performansınızı optimize etmenize yardımcı olabilir.
API'yi kullanarak neler oluşturabilirsiniz?
Text Suggestions API, aşağıdakileri yapmanıza yardımcı olur:
- Ürün resminize ve/veya ürün özelliklerinize göre önerilen ürün başlıkları ve açıklamaları.
- Ürünleriniz için SEO'ya uygun başlıklar
- Ürünleriniz için özel olarak biçimlendirilmiş başlıklar
- Ürün feed'inizdeki ürün açıklamaları
Açıklamalarda kullanılacak üslubu da belirleyebilir ve tüm ürün listelemelerinizde tutarlılık sağlayabilirsiniz.
Hızlı başlangıç kılavuzu
GenerateProductTextSuggestions
yöntemi, ürün bilgilerinizi kullanarak ürün başlıkları ve açıklamaları oluşturabilir veya optimize edebilir.
API şunları kabul eder:
- Ürün Özellikleri (JSON Sözlüğü): Ürün özelliklerini (ör.
{"title": "White Tee", "brand": "MyBrand", "size": "XL"}
) içeren bir JSON nesnesi - Ürün resmi: Ürün resmine yönlendiren bir URI (ör.
{"uri": "https://my-store.com/img/1.png"}
) - Başlık Biçimlendirme Seçenekleri: Başlık oluşturmayı özelleştirmeye yönelik parametreler. Örneğin:
attribute_separator
: Özellikler arasındaki ayırıcıyı belirtir.target_language
: Çıktı dilini ayarlar.attribute_order
: Oluşturulan başlıkta özelliklerin sırasını tanımlar.
- Veri etiketleme örnekleri: Açıklamadan başlık oluşturma ile ilgili bir örneğe göz atın.
- İş akışı kimliği (
output_spec.workflow_id
):output_spec
nesnesindekiworkflow_id
alanı, metin oluşturma türünü belirler:title
: Ürün başlığını oluşturur veya optimize eder.description
: Ürün açıklamasını oluşturur veya optimize eder.tide
: Hem ürün başlığını hem de açıklamasını oluşturur veya optimize eder.
Örnekler
Aşağıda, farklı ürün verisi girişlerinden başlık veya açıklama ya da her ikisini de oluşturmak veya optimize etmek için API'nin kullanıldığı örnekler verilmiştir. Ayrıca, sık karşılaşılan hataları ve sorunları ve çözümlerini de sunuyoruz.
Optimize edilmiş başlık oluşturma
Bu örnekte, en uygun başlığın nasıl oluşturulacağı gösterilmektedir.
İstek
İstek metni, başlık optimizasyonu için kullanılacak ürün bilgilerini içerir. İstek yapısının bir örneğini aşağıda görebilirsiniz:
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"
}
}
Yanıt
Şu gibi bir yanıt alabilirsiniz:
{
"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"
},
}
}
}
Yalnızca bir resimden başlık oluşturma
Örnekte, ürün resmi sağlama ve optimum başlık oluşturma gösterilmektedir.
İstek
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": "-"
}
}
Yanıt
{
"title": {
"text": "Rustic Ceramic & Leather Leaves Necklace"
},
"metadata": {
"metadata": {
"attributes": {
"material": "Rustic Ceramic & Leather",
"pattern": "Leaves",
"product": "Necklace"
},
}
}
}
Açıklamadan başlık oluşturma
Bu örnekte, ürün açıklamasının nasıl sağlanacağı ve en uygun başlığın nasıl oluşturulacağı gösterilmektedir.
İstek
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",
}
}
Yanıt
{
"title": {
"text": "Nike Dunks Red Size 12"
},
"metadata": {
"metadata": {
"attributes": {
"brand": "Nike",
"color": "Red",
"size": "12",
"product": "Dunks"
},
}
}
}
Başlık ve açıklamadan başlıkları optimize etme (özel örnekle birlikte)
Bu örnekte, yapay zekanın tanımlamasını istediğimiz ürün özelliklerini ve çıkıştaki özellik sıralamasını açıkça etiketliyoruz.
İstek
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"
}
}
]
}
Yanıt
{
"title": {
"text": "Luxe Beauty Dark Brown Volumizing & Lengthening Mascara"
},
"metadata": {
"metadata": {
"attributes": {
"brand": "Luxe Beauty",
"colour": "Dark Brown",
"mascara_type": "Volumizing & Lengthening",
"product": "Mascara"
},
}
}
}
Başlıktan açıklama oluşturma
Bu örnekte, ürün başlığının nasıl sağlanacağı ve API'den karşılık gelen bir ürün açıklaması oluşturmasının nasıl isteneceği gösterilmektedir.
İstek
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"
}
}
Yanıt
{
"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.
"
},
}
Ürün özelliklerinden (ör. marka ve renk) başlık ve açıklama oluşturma
Bu örnekte, optimum ürün başlığı ve açıklaması oluşturmak için ürün özelliklerinin nasıl sağlanacağı gösterilmektedir.
İstek
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"
}
}
Yanıt
{
"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."
},
}
Hedef Dil Desteği
Bu alan, API yanıtında oluşturulan açıklama metninin dilini belirtir. target_language
parametresini output_spec
parametrelerinin bir parçası olarak ekleyebilirsiniz:
{
"output_spec": {
"target_language": "language"
}
}
Örnek Değerler:
"korean" (Korean)
"english" (English)
"spanish" (Spanish)
"french" (French)
Örnek İstek
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",
}
}
Yanıt
{
"description": {
"text": "カリフォルニアの黒いコーヒー豆は、あなたの鼻をくすぐる、甘く、フローラルな香りです。この香りは、コーヒー豆の豊かな香りと、ジャスミンとバラの繊細な花の香りをブレンドしたものです。カリフォルニアの黒いコーヒー豆は、あなたの家を居心地の良いカフェに変え、あなたをリラックスした気分にさせてくれるでしょう。この香りは、コーヒー好きにも、フローラルな香り好きにも最適です。カリフォルニアの黒いコーヒー豆で、あなたの家を幸せな香りで満たしましょう!."
},
}
Açıklama oluşturma için ses tonunu kişiselleştirme
Markanızı oluşturmanıza ve online mağazanızı diğerlerinden ayırmanıza yardımcı olması için oluşturulan açıklamalarınızın üslubunu kişiselleştirebilirsiniz. Text API iki seçenek sunar:
- Önceden Tanımlanmış Ton Seçimi: Yeni açıklamalar oluşturmak için ton listesinden seçim yapabilirsiniz. Listede şu üslup stilleri yer alır:
- Varsayılan: Basit, net ve zarif.
- Eğlenceli: Neşeli, olumlu bir dil, mizah (şakalar, kelime oyunları) ve abartı (ironi, alay veya emoji yok) kullanır.
- Resmi: Standart İngilizce, doğru dil bilgisi, tam cümleler, argo veya kısaltma yok.
- İkna edici: Okuyucuyu ikna etmek için mantıklı, kısa ve argüman odaklı.
- Sohbet tonunda: Samimi, kolay anlaşılır ve günlük dil.
- Markaya Özgü Üslup: Markanızın üslubuna uygun mevcut açıklamalar veya diğer metin öğelerini sağlayabilirsiniz. Üretken yapay zeka modeli, metnin tonunu analiz eder ve şu unsurlara göre bir "yazma stili tanımlayıcısı" oluşturur:
- Resmiyet (ör. resmi, samimi)
- Ayrıntı düzeyi (ör. kısa, çok ayrıntılı)
- Üslup (ör. profesyonel, bilgilendirici, olumlu, ikna edici)
- Cümle yapısı (ör. "Az bağlaçlı basit cümle")
- En sık kullanılan kelimeler ve kelime öbekleri
İstemci kitaplıkları
İsteklerinizi göndermek için istemci kitaplıklarını kullanmanızı öneririz. İstemci kitaplıklarını sizinle paylaşacağız. Bu kitaplıkları Maven projenize yükleyebilirsiniz.
Kod örnekleri
Kimlik doğrulama yönteminizi seçin ve bu kod örneklerini talimatları kullanarak ayarlayın. Metin önerileri oluşturmak için kullanabileceğiniz bir örneği aşağıda bulabilirsiniz.
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);
}
}
Sık karşılaşılan hatalar ve sorunlar
Sık karşılaşılan bazı hatalar ve çözümleri aşağıda açıklanmıştır.
Metin önerileri oluşturmak için ürün bilgileri gerekir
Aşağıdaki hata mesajını alırsanız
Error message:
"error": {
"code": 400,
"message": "[product_info] Product info is required to generate text suggestions.",
"status": "INVALID_ARGUMENT",
...
}
İstek gövdesine product_info
ekleyin ve product_attributes
veya product_image
alanlarından en az birini doğru şekilde doldurun.
Örneğin, bu gönderinin yayınlanması hataya neden olur.
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"output_spec": {
"workflow_id": "title"
}
}
Metin önerileri oluşturmak için product_info alanlarından en az biri gereklidir.
Bu hata
{
"error": {
"code": 400,
"message": "[product_info.product_attributes] At least one field of product_info is required to generate text suggestions.",
"status": "INVALID_ARGUMENT",
...
}
, istek gövdesine en az bir product_info
alanı eklemeniz gerektiğini gösterir.
Örneğin, bu mesajın yayınlanması hataya neden olur.
POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions
{
"product_info": {
},
"output_spec": {
"workflow_id": "title"
}
}
Bunun yerine aşağıdakiler gibi ifadeler kullanın:
"product_info": {
"product_attributes": {
"description": "Selling size 12 Nike dunks. Oh they are red by the way!"
}
}
veya
"product_info": {
"product_image":{
"uri": "https://cdn.shopify.com/s/files/1/0653/5879/0892/products/1672082339438_550x825.jpg?v=1672082415"
}
}
Her title_example öğesinde (bir şey) gereklidir
Aşağıdaki dört örnekteki gibi hatalar
{
"error": {
"code": 400,
"message": "[title_examples.product_info] At least one field of product_info is required in each title_example.",
"status": "INVALID_ARGUMENT",
...
}
veya
{
...
"message": "[title_examples.category] Category is required in each title_example.",
...
}
veya
{
...
"message": "[title_examples.title_format] Title format is required in each title_example.",
...
}
veya
{
...
"message": "[title_examples.final_product_info] At least one field of final_product_info is required in each title_example.",
...
}
zorunlu bir alt alanı doldurmadığınızı gösterir.
Örneğin, aşağıdaki istek hata oluşturur.
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": []
}
Bu sorunu çözmek için, istekte belirtilen her title_example için aşağıdaki alt alanların tümünü doldurun:
product_info
category
title_format
final_product_info
Aşağıda, çalışan bir örnek verilmiştir:
{
"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",
}
}
]
}
Desteklenmeyen workflow_id
Bu tür hatalar
{
"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",
...
}
gibi bir istekten kaynaklanır.
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"
}
}
İstek, workflow_id
değerini "attributes" olarak ayarlıyor ancak bu alan yalnızca aşağıdaki değerlerden birini destekliyor:
- title: Ürün başlığını oluşturur veya optimize eder.
- description: Ürün açıklamasını oluşturur veya optimize eder.
- tide: Hem ürün başlığını hem de açıklamasını oluşturur veya optimize eder.
Desteklenmeyen ton
"Desteklenmeyen ton" hatası (ör.
{
"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",
...
}
gibi bir istekten kaynaklanabilir.
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
değerinin "cheerful" olarak ayarlandığını ancak bu alanın yalnızca aşağıdaki değerlerden birini desteklediğini unutmayın:
- default: Basit, net ve zarif.
- Eğlenceli: Neşeli, olumlu bir dil, mizah (şakalar, kelime oyunları) ve abartı (ironi, alay veya emoji yok) kullanır.
- Resmi (formal): Standart İngilizce, doğru dil bilgisi, tam cümleler, argo veya kısaltma yok.
- İkna edici (persuasive): Okuyucuyu ikna etmek için mantıklı, kısa ve argüman odaklı.
- Sohbet tonunda: Samimi, kolay anlaşılır ve günlük dil.