產生文字建議

Text Suggestions API 會運用 Product Studio API 的生成式 AI 工具，生成及調整產品名稱和說明。你可以藉此提升顧客參與度和轉換率，並簡化管理及更新產品資訊的程序。Product Studio API 的功能可協助你提升零售業績。

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

Text Suggestions API 可協助您執行下列動作：

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

你也可以指定說明的語氣，並確保所有產品資訊的語氣一致。

快速入門導覽課程

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：定義所產生標題中的屬性順序。
  • 資料標籤範例：請參閱如何根據說明生成標題的範例。
  • 工作流程 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」，但這個欄位只支援下列其中一個值：

  • 名稱：生成或調整產品名稱。
  • 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」，但這個欄位僅支援下列其中一個值：

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