本頁面由 Cloud Translation API 翻譯而成。

產生文字建議

Text Suggestions API 會運用 Product Studio API 的生成式 AI 工具，產生及最佳化產品名稱和說明。您可以使用這項功能來提高顧客參與度和轉換率。

您可以使用 API 產生哪些內容？

系統會根據產品圖片和/或產品屬性，提供建議的產品名稱和說明。
產品的搜尋引擎最佳化名稱
產品的自訂格式標題
產品動態饋給中的產品說明

你也可以為說明指定語氣。

快速入門導覽課程

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 回應中產生的說明文字語言。您可以將 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": "カリフォルニアの黒いコーヒー豆は、あなたの鼻をくすぐる、甘く、フローラルな香りです。この香りは、コーヒー豆の豊かな香りと、ジャスミンとバラの繊細な花の香りをブレンドしたものです。カリフォルニアの黒いコーヒー豆は、あなたの家を居心地の良いカフェに変え、あなたをリラックスした気分にさせてくれるでしょう。この香りは、コーヒー好きにも、フローラルな香り好きにも最適です。カリフォルニアの黒いコーヒー豆で、あなたの家を幸せな香りで満たしましょう！."
  },
}

為說明產生功能設定語氣個人化

為了建立品牌形象，並讓你的網路商店與眾不同，你可以自訂產生的說明文字的語氣。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);
  }
}

常見錯誤和問題

以下列舉幾個常見陷阱和解決方法。

必須提供產品資訊，才能產生文字建議

如果您收到下列錯誤訊息

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_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：產生或最佳化產品名稱。
description：產生或最佳化產品說明。
tide：產生或調整產品名稱和說明。

不支援的音調

「Unsupported tone」錯誤，例如

{
  "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」，但這個欄位僅支援下列其中一個值：

預設：簡單、清楚且優雅。
輕鬆活潑：使用輕鬆、正面、幽默 (笑話、雙關語) 和誇張的用語 (不含反諷、諷刺或表情符號)。
正式：標準英文、正確的文法、完整的句子，不使用俚語或縮寫。
說服力：以邏輯、簡潔且以論點為導向的方式說服讀者。
對話式：使用親切、易懂的日常用語。