Generowanie sugestii tekstowych

Interfejs Text Suggestions API wykorzystuje narzędzia generatywnej AI z interfejsu Product Studio API do generowania i optymalizowania tytułów oraz opisów produktów. Możesz go używać do zwiększania zaangażowania klientów i liczby konwersji oraz do usprawniania procesu zarządzania informacjami o produktach i ich aktualizowania. Funkcje interfejsu Product Studio API mogą Ci pomóc w optymalizacji wyników sprzedaży detalicznej.

Co możesz generować za pomocą interfejsu API?

Interfejs Text Suggestions API pomaga w tych czynnościach:

  • sugerowane tytuły i opisy produktów na podstawie zdjęcia produktu lub atrybutów produktu;
  • tytuły produktów zoptymalizowane pod kątem SEO,
  • Tytuły produktów w formacie niestandardowym
  • opisy produktów z pliku danych o produktach,

Możesz też określić ton opisu i zachować spójność we wszystkich informacjach o produktach.

Krótkie wprowadzenie

Metoda GenerateProductTextSuggestions może generować lub optymalizować tytuły i opisy produktów na podstawie informacji o produktach.

Interfejs API akceptuje:

  • Atrybuty produktu (słownik JSON): obiekt JSON zawierający atrybuty produktu (np. {"title": "White Tee", "brand": "MyBrand", "size": "XL"}).
  • Zdjęcie produktu: identyfikator URI wskazujący zdjęcie produktu (np. {"uri": "https://my-store.com/img/1.png"}).
  • Opcje formatowania tytułu: parametry dostosowywania generowania tytułu, w tym:
    • attribute_separator: określa separator między atrybutami.
    • target_language: ustawia język wygenerowanych treści.
    • attribute_order: określa kolejność atrybutów w wygenerowanym tytule.
  • Przykłady etykietowania danych: zobacz przykład generowania tytułu na podstawie opisu.
  • Identyfikator procesu (output_spec.workflow_id): pole workflow_id w obiekcie output_spec określa typ generowania tekstu:
    • title: generuje lub optymalizuje tytuł produktu.
    • description: generuje lub optymalizuje opis produktu.
    • tide: generuje lub optymalizuje zarówno tytuł, jak i opis produktu.

Przykłady

Poniżej znajdziesz przykłady użycia interfejsu API do generowania lub optymalizowania tytułu lub opisu albo obu tych elementów na podstawie różnych danych wejściowych o produktach. Przedstawiamy też typowe błędy i problemy oraz sposoby ich rozwiązywania.

Generowanie zoptymalizowanych tytułów

W tym przykładzie pokazujemy, jak wygenerować optymalny tytuł.

Żądanie

Treść żądania zawiera informacje o produkcie, które mają być użyte do optymalizacji tytułu. Oto przykład struktury żądania:

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"
   }
}

Odpowiedź

Możesz się spodziewać odpowiedzi w stylu

{
  "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"
      },
    }
  }
}

Generowanie tytułu na podstawie samego obrazu

Przykład pokazuje, jak podać obraz produktu i wygenerować optymalny tytuł.

Żądanie

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": "-"
   }
}

Odpowiedź

{
  "title": {
    "text": "Rustic Ceramic & Leather Leaves Necklace"
  },
  "metadata": {
    "metadata": {
      "attributes": {
        "material": "Rustic Ceramic & Leather",
        "pattern": "Leaves",
        "product": "Necklace"
      },
    }
  }
}

Generowanie tytułu na podstawie opisu

Przykład pokazuje, jak podać opis produktu i wygenerować optymalny tytuł.

Żądanie

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",
   }
}

Odpowiedź

{
  "title": {
    "text": "Nike Dunks Red Size 12"
  },
  "metadata": {
    "metadata": {
      "attributes": {
        "brand": "Nike",
        "color": "Red",
        "size": "12",
        "product": "Dunks"
      },
    }
  }
}

Optymalizowanie tytułów na podstawie tytułu i opisu (wraz z niestandardowym przykładem)

W tym przykładzie wyraźnie oznaczamy atrybuty produktu, które ma zidentyfikować AI, oraz kolejność atrybutów w danych wyjściowych.

Żądanie

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"
      }
    }
  ]
}

Odpowiedź

{
  "title": {
    "text": "Luxe Beauty Dark Brown Volumizing & Lengthening Mascara"
  },
  "metadata": {
    "metadata": {
      "attributes": {
        "brand": "Luxe Beauty",
        "colour": "Dark Brown",
        "mascara_type": "Volumizing & Lengthening",
        "product": "Mascara"
      },
    }
  }
}

Generowanie opisu na podstawie tytułu

Przykład pokazuje, jak podać tytuł produktu i poprosić interfejs API o wygenerowanie odpowiedniego opisu produktu.

Żądanie

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"
   }
}

Odpowiedź

{
  "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.
"
  },
}

Generowanie tytułu i opisu na podstawie atrybutów produktu (takich jak marka i kolor)

Ten przykład pokazuje, jak podać atrybuty produktu, aby wygenerować optymalny tytuł i opis produktu.

Żądanie

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"
   }
}

Odpowiedź

{
  "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."
  },
}

Obsługa języków docelowych

To pole określa język tekstu opisu wygenerowanego w odpowiedzi interfejsu API. Możesz dodać target_language jako część parametrów output_spec:

{
    "output_spec": {
        "target_language": "language"
    }
}

Przykładowe wartości:

"korean" (Korean)
"english" (English)
"spanish" (Spanish)
"french" (French)

Przykładowe żądanie

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",
   }
}

Odpowiedź

{
  "description": {
    "text": "カリフォルニアの黒いコーヒー豆は、あなたの鼻をくすぐる、甘く、フローラルな香りです。この香りは、コーヒー豆の豊かな香りと、ジャスミンとバラの繊細な花の香りをブレンドしたものです。カリフォルニアの黒いコーヒー豆は、あなたの家を居心地の良いカフェに変え、あなたをリラックスした気分にさせてくれるでしょう。この香りは、コーヒー好きにも、フローラルな香り好きにも最適です。カリフォルニアの黒いコーヒー豆で、あなたの家を幸せな香りで満たしましょう！."
  },
}

Personalizacja tonu głosu w przypadku generowania opisów

Aby wyróżnić swoją markę i odróżnić sklep internetowy od innych, możesz spersonalizować styl wygenerowanych opisów. Interfejs Text API oferuje 2 opcje:

  • Wstępnie zdefiniowane opcje tonu: możesz wybrać ton z listy, aby wygenerować nowe opisy. Lista zawiera te style tonu:
    • Domyślny: prosty, przejrzysty i elegancki.
    • Żartobliwy: lekki, używający pozytywnego języka, humoru (żarty, kalambury) i przesady (bez ironii, sarkazmu ani emotikonów).
    • Formalny: standardowy język angielski, poprawna gramatyka, pełne zdania, bez slangu i skrótów.
    • Przekonujący: logiczny, zwięzły i oparty na argumentach, aby przekonać czytelnika.
    • Konwersacyjny: przyjazny, łatwy do zrozumienia, codzienny język.
  • Ton głosu marki: możesz podać istniejące opisy lub inne komponenty tekstowe w tonie głosu Twojej marki. Model generatywnej AI przeanalizuje ton tekstu i wygeneruje „opis stylu pisania” na podstawie tych aspektów:
    • Stopień formalności (np. formalny, nieformalny)
    • Szczegółowość (np. zwięzłość, bardzo szczegółowe)
    • Ton (np. profesjonalny, informacyjny, pozytywny, perswazyjny)
    • Struktura zdania (np. „proste zdanie z niewielką liczbą spójników”)
    • Najczęściej używane słowa i wyrażenia

Biblioteki klienta

Do przesyłania żądań zalecamy używanie bibliotek klienta. Udostępnimy Ci biblioteki klienta, które możesz zainstalować w projekcie Maven.

Przykładowe fragmenty kodu

Wybierz metodę uwierzytelniania i skonfiguruj te przykłady kodu, korzystając z tych instrukcji. Oto przykład, którego możesz użyć do generowania sugestii tekstu.

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);
  }
}

Typowe błędy i problemy

Oto kilka typowych problemów i ich rozwiązań.

Informacje o produkcie są wymagane do generowania sugestii tekstowych

Jeśli pojawi się ten komunikat o błędzie:

Error message:
"error": {
    "code": 400,
    "message": "[product_info] Product info is required to generate text suggestions.",
    "status": "INVALID_ARGUMENT",
 ...
}

dodaj product_info w treści żądania i prawidłowo wypełnij co najmniej jedną z tych wartości: product_attributes lub product_image.

Na przykład opublikowanie tego spowoduje błąd.

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "output_spec": {
      "workflow_id": "title"
   }
}

Aby generować sugestie tekstowe, musisz wypełnić co najmniej 1 pole w sekcji product_info

Ten błąd

{
  "error": {
    "code": 400,
    "message": "[product_info.product_attributes] At least one field of product_info is required to generate text suggestions.",
    "status": "INVALID_ARGUMENT",
 ...
}

oznacza, że w treści żądania musisz uwzględnić co najmniej 1 pole product_info.

Na przykład opublikowanie tego spowoduje błąd.

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
   },
   "output_spec": {
      "workflow_id": "title"
   }
}

Zamiast tego użyj czegoś takiego:

   "product_info": {
        "product_attributes": {
         "description": "Selling size 12 Nike dunks. Oh they are red by the way!"
      }
   }

lub

"product_info": {
    "product_image":{
        "uri": "https://cdn.shopify.com/s/files/1/0653/5879/0892/products/1672082339438_550x825.jpg?v=1672082415"
    }
}

(Something) is required in each title_example

Błędy takie jak w tych 4 przykładach

{
  "error": {
    "code": 400,
    "message": "[title_examples.product_info] At least one field of product_info is required in each title_example.",
    "status": "INVALID_ARGUMENT",
 ...
}

lub

{
  ...
    "message": "[title_examples.category] Category is required in each title_example.",
  ...
}

lub

{
  ...
    "message": "[title_examples.title_format] Title format is required in each title_example.",
  ...
}

lub

{
  ...
    "message": "[title_examples.final_product_info] At least one field of final_product_info is required in each title_example.",
  ...
}

oznacza, że nie wypełniono wymaganego pola podrzędnego.

Na przykład to żądanie wygeneruje błąd.

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": []
}

Aby rozwiązać ten problem, w przypadku każdego elementu title_example określonego w żądaniu wypełnij wszystkie te pola podrzędne:

  • product_info
  • category
  • title_format
  • final_product_info

Oto przykład, który działa:

{
   "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",
      }
    }
  ]
}

Nieobsługiwany identyfikator workflow_id

Ten typ błędu

{
  "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",
 ...
}

wyniknie z żądania takiego jak

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"
   }
}

Żądanie ustawia wartość workflow_id na „attributes”, ale to pole obsługuje tylko jedną z tych wartości:

  • title: generuje lub optymalizuje tytuł produktu.
  • description: generuje lub optymalizuje opis produktu.
  • tide: generuje lub optymalizuje zarówno tytuł, jak i opis produktu.

Nieobsługiwany ton

Błąd „Nieobsługiwany ton”, np.

{
  "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",
 ...
}

wynikłoby z żądania takiego jak

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"
   }
}

Zwróć uwagę, że pole tone ma wartość „cheerful”, ale obsługuje tylko jedną z tych wartości:

  • default: prosty, przejrzysty i elegancki;
  • żartobliwy: lekki, używający pozytywnego języka, humoru (żarty, kalambury) i przesady (bez ironii, sarkazmu ani emotikonów).
  • formalny: standardowy język angielski, poprawna gramatyka, pełne zdania, brak slangu i skrótów.
  • perswazyjny: logiczny, zwięzły i oparty na argumentach, aby przekonać czytelnika.
  • konwersacyjny: przyjazny, zrozumiały, codzienny język.