Générer des suggestions de texte

L'API Text Suggestions utilise les outils d'IA générative de l'API Product Studio pour générer et optimiser les titres et les descriptions de produits. Vous pouvez l'utiliser pour améliorer l'engagement et les conversions des clients, et pour simplifier la gestion et la mise à jour des informations sur les produits. Les fonctionnalités de l'API Product Studio peuvent vous aider à optimiser vos performances commerciales.

Que pouvez-vous générer à l'aide de l'API ?

L'API Text Suggestions vous permet d'effectuer les opérations suivantes :

  • Des titres et des descriptions de produits suggérés en fonction de l'image et/ou des attributs de vos produits.
  • Titres optimisés pour le référencement naturel de vos produits
  • Titres de vos produits au format personnalisé
  • Descriptions des produits issues de votre flux de produits

Vous pouvez également spécifier le ton des descriptions et assurer la cohérence de toutes vos fiches produit.

Guide de démarrage rapide

La méthode GenerateProductTextSuggestions peut générer ou optimiser les titres et les descriptions de produits à l'aide de vos informations produit.

L'API accepte :

  • Attributs du produit (dictionnaire JSON) : objet JSON contenant les attributs du produit (par exemple, {"title": "White Tee", "brand": "MyBrand", "size": "XL"}).
  • Image du produit : URI pointant vers l'image du produit (par exemple, {"uri": "https://my-store.com/img/1.png"})
  • Options de mise en forme du titre : paramètres permettant de personnaliser la génération des titres, y compris :
    • attribute_separator : spécifie le séparateur entre les attributs.
    • target_language : définit la langue de sortie.
    • attribute_order : définit l'ordre des attributs dans le titre généré.
  • Exemples d'étiquetage de données : découvrez comment générer un titre à partir d'une description.
  • ID du workflow (output_spec.workflow_id) : le champ workflow_id de l'objet output_spec détermine le type de génération de texte :
    • title : génère ou optimise le titre du produit.
    • description : génère ou optimise la description du produit.
    • tide : génère ou optimise le titre et la description du produit.

Exemples

Voici des exemples d'utilisation de l'API pour générer ou optimiser un titre ou une description, ou les deux, à partir de différentes entrées de données produit. Nous présentons également les erreurs et problèmes courants, ainsi que leurs solutions.

Génération de titres optimisés

L'exemple montre comment générer un titre optimal.

Requête

Le corps de la requête contient les informations sur le produit à utiliser pour optimiser le titre. Voici un exemple de structure de requête :

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

Réponse

Vous pouvez vous attendre à une réponse comme

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

Générer un titre à partir d'une image uniquement

L'exemple montre comment fournir une image de produit et générer un titre optimal.

Requête

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

Réponse

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

Générer un titre à partir d'une description

L'exemple montre comment fournir une description de produit et générer un titre optimal.

Requête

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

Réponse

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

Optimiser des titres à partir d'un titre et d'une description (avec un exemple personnalisé)

Dans cet exemple, nous indiquons explicitement les attributs de produit que nous souhaitons que l'IA identifie, ainsi que l'ordre des attributs dans le résultat.

Requête

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

Réponse

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

Générer une description à partir d'un titre

L'exemple montre comment fournir un titre de produit et demander à l'API de générer une description de produit correspondante.

Requête

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

Réponse

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

Générer un titre et une description à partir des attributs du produit (comme la marque et la couleur)

Cet exemple montre comment fournir des attributs de produit pour générer un titre et une description optimaux.

Requête

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

Réponse

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

Langues cibles disponibles

Ce champ spécifie la langue du texte de description généré dans la réponse de l'API. Vous pouvez ajouter target_language aux paramètres output_spec :

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

Exemples de valeurs :

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

Exemple de requête

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

Réponse

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

Personnalisation du ton pour la génération de descriptions

Pour vous aider à établir votre marque et à différencier votre boutique en ligne des autres, vous pouvez personnaliser le ton de vos descriptions générées. L'API Text propose deux options :

  • Sélection de ton prédéfini : vous pouvez choisir parmi une liste de tons pour générer de nouvelles descriptions. La liste inclut les styles de ton suivants :
    • Par défaut : simple, clair et élégant.
    • Enjoué : ton léger, langage positif, humour (blagues, jeux de mots) et exagération (sans ironie, sarcasme ni emoji).
    • Formel : anglais standard, grammaire correcte, phrases complètes, pas d'argot ni de contractions.
    • Persuasif : logique, concis et axé sur les arguments pour convaincre le lecteur.
    • Conversationnel : langage courant, simple et facile à comprendre.
  • Ton spécifique à la marque : vous pouvez fournir des descriptions existantes ou d'autres composants textuels dans le ton de votre marque. Le modèle d'IA générative analysera le ton du texte et générera un "descripteur de style d'écriture" en fonction des aspects suivants :
    • Registre (formel, informel, etc.)
    • Niveau de détail (par exemple, concis, très détaillé)
    • Ton (par exemple, professionnel, informatif, positif, persuasif)
    • Structure des phrases (par exemple, "phrase simple avec peu de conjonctions")
    • Mots et expressions les plus fréquents

Bibliothèques clientes

Nous vous recommandons d'utiliser des bibliothèques clientes pour envoyer vos requêtes. Nous vous fournirons les bibliothèques clientes que vous pourrez installer dans votre projet Maven.

Exemples de code

Choisissez votre méthode d'authentification et configurez ces exemples de code en suivant ces instructions. Voici un exemple permettant de générer des suggestions de texte.

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

Erreurs et problèmes courants

Voici quelques pièges courants et les solutions correspondantes.

Les informations sur le produit sont requises pour générer des suggestions de texte

Si vous recevez le message d'erreur suivant :

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

Ajoutez product_info dans le corps de la requête et renseignez correctement au moins l'une des valeurs product_attributes ou product_image.

Par exemple, la publication suivante générera une erreur.

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

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

Au moins un champ de product_info est requis pour générer des suggestions de texte

Cette erreur

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

indique que vous devez inclure au moins un champ product_info dans le corps de la requête.

Par exemple, la publication suivante générera une erreur.

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

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

Utilisez plutôt quelque chose comme

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

ou

"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

Erreurs telles que les quatre exemples suivants

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

ou

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

ou

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

ou

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

indiquent que vous n'avez pas renseigné un sous-champ obligatoire.

Par exemple, la requête suivante générerait une erreur.

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

Pour résoudre ce problème, pour chaque title_example spécifié dans la requête, renseignez tous les sous-champs suivants :

  • product_info
  • category
  • title_format
  • final_product_info

Voici un exemple qui fonctionne :

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

ID workflow non compatible

Ce type d'erreur

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

résulterait d'une requête telle que

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

La requête définit workflow_id sur "attributes", mais ce champ n'accepte qu'une des valeurs suivantes :

  • title : génère ou optimise le titre du produit.
  • description : génère ou optimise la description du produit.
  • tide : génère ou optimise le titre et la description du produit.

Ton non pris en charge

Une erreur "Tonalité non acceptée" telle que

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

résulterait d'une requête telle que

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

Notez que tone est défini sur "joyeux", mais que ce champ n'accepte qu'une des valeurs suivantes :

  • default : simple, clair et élégant.
  • Enjoué : léger, utilisant un langage positif, de l'humour (blagues, jeux de mots) et de l'exagération (sans ironie, sarcasme ni emoji).
  • formal : anglais standard, grammaire correcte, phrases complètes, pas d'argot ni de contractions.
  • persuasif : logique, concis et axé sur les arguments pour convaincre le lecteur.
  • Conversationnel : langage courant, simple et convivial.