Questa pagina è stata tradotta dall'API Cloud Translation.

Generare suggerimenti di testo

L'API Text Suggestions sfrutta gli strumenti di AI generativa dell'API Product Studio per generare e ottimizzare titoli e descrizioni dei prodotti. Puoi utilizzarlo per migliorare il coinvolgimento e le conversioni dei clienti e semplificare il processo di gestione e aggiornamento delle informazioni sui prodotti. Le funzionalità dell'API Product Studio possono aiutarti a ottimizzare il rendimento della tua attività di vendita al dettaglio.

Cosa puoi generare utilizzando l'API?

L'API Text Suggestions ti aiuta a:

Titoli e descrizioni dei prodotti suggeriti in base all'immagine e/o agli attributi del prodotto.
Titoli ottimizzati per la SEO per i tuoi prodotti
Titoli con formattazione personalizzata per i tuoi prodotti
Descrizioni dei prodotti dal feed dei prodotti

Puoi anche specificare il tono di voce per le descrizioni e mantenere la coerenza in tutte le schede di prodotto.

Guida rapida

Il metodo GenerateProductTextSuggestions può generare o ottimizzare titoli e descrizioni dei prodotti utilizzando le informazioni sui prodotti.

L'API accetta:

Attributi prodotto (dizionario JSON): un oggetto JSON contenente gli attributi del prodotto (ad esempio, {"title": "White Tee", "brand": "MyBrand", "size": "XL"})
Immagine prodotto:un URI che rimanda all'immagine del prodotto (ad esempio, {"uri": "https://my-store.com/img/1.png"})
Opzioni di formattazione del titolo: parametri per personalizzare la generazione del titolo, tra cui:
- attribute_separator: specifica il separatore tra gli attributi.
- target_language: imposta la lingua di output.
- attribute_order: definisce l'ordine degli attributi nel titolo generato.
Esempi di etichettatura dei dati: vedi un esempio di come generare un titolo da una descrizione.
ID flusso di lavoro (output_spec.workflow_id): il campo workflow_id all'interno dell'oggetto output_spec determina il tipo di generazione di testo:
- title: genera o ottimizza il titolo del prodotto.
- description: genera o ottimizza la descrizione del prodotto.
- tide: genera o ottimizza sia il titolo che la descrizione del prodotto.

Esempi

Di seguito sono riportati alcuni esempi di utilizzo dell'API per generare o ottimizzare un titolo o una descrizione o entrambi a partire da diversi input di dati di prodotto. Presentiamo anche errori e problemi comuni e le relative soluzioni.

Generazione di titoli ottimizzati

L'esempio mostra come generare un titolo ottimale.

Richiesta

Il corpo della richiesta contiene le informazioni sul prodotto da utilizzare per l'ottimizzazione del titolo. Ecco un esempio della struttura della richiesta:

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

Risposta

Puoi aspettarti una risposta come

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

Generare un titolo solo da un'immagine

L'esempio mostra come fornire un'immagine prodotto e generare un titolo ottimale.

Richiesta

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

Risposta

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

Generare un titolo da una descrizione

L'esempio mostra come fornire una descrizione del prodotto e generare un titolo ottimale.

Richiesta

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

Risposta

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

Ottimizzare i titoli da un titolo e una descrizione (insieme a un esempio personalizzato)

In questo esempio, etichettiamo esplicitamente gli attributi del prodotto che vogliamo che l'AI identifichi e l'ordine degli attributi nell'output.

Richiesta

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

Risposta

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

Generare una descrizione da un titolo

L'esempio mostra come fornire un titolo del prodotto e chiedere all'API di generare una descrizione del prodotto corrispondente.

Richiesta

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

Risposta

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

Generare un titolo e una descrizione a partire dagli attributi del prodotto (come marca e colore)

Questo esempio mostra come fornire gli attributi del prodotto per generare un titolo e una descrizione del prodotto ottimali.

Richiesta

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

Risposta

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

Supporto delle lingue di destinazione

Questo campo specifica la lingua del testo descrittivo generato nella risposta dell'API. Puoi aggiungere target_language come parte dei parametri output_spec:

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

Valori di esempio:

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

Esempio di richiesta

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

Risposta

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

Personalizzazione del tono di voce per la generazione di descrizioni

Per contribuire a definire il tuo brand e differenziare il tuo negozio online dagli altri, puoi personalizzare il tono di voce delle descrizioni generate. L'API Text offre due opzioni:

Selezione di toni predefiniti: puoi scegliere da un elenco di toni per generare nuove descrizioni. L'elenco include i seguenti stili di tono:
- Predefinito:semplice, chiaro ed elegante.
- Scherzoso: spensierato, con un linguaggio positivo, umorismo (battute, giochi di parole) ed esagerazione (senza ironia, sarcasmo o emoji).
- Formale:inglese standard, grammatica corretta, frasi complete, nessun slang o contrazione.
- Persuasivo: logico, conciso e basato su argomentazioni per convincere il lettore.
- Conversazionale:linguaggio amichevole, facile da capire e di uso quotidiano.
Tono specifico del brand:puoi fornire descrizioni esistenti o altri asset di testo con lo stile del tuo brand. Il modello di AI generativa analizzerà il tono del testo e genererà un "descrittore dello stile di scrittura" in base a questi aspetti:
- Formalità (ad es. formale, informale)
- Preferenze di lettura (ad esempio, concisa, molto dettagliata)
- Tono (ad esempio, professionale, informativo, positivo, persuasivo)
- Struttura della frase (ad esempio, "frase semplice con poche congiunzioni")
- Parole e frasi più frequenti utilizzate

Librerie client

Ti consigliamo di utilizzare le librerie client per inviare le richieste. Condivideremo con te le librerie client che potrai installare nel tuo progetto Maven.

Esempi di codice

Scegli il metodo di autenticazione e configura questi esempi di codice seguendo queste istruzioni. Ecco un esempio che puoi utilizzare per generare suggerimenti di testo.

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

Errori e problemi comuni

Di seguito sono riportati alcuni problemi comuni e le relative soluzioni.

Per generare suggerimenti di testo sono necessarie le informazioni sul prodotto

Se ricevi il seguente messaggio di errore

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

aggiungi product_info nel corpo della richiesta e compila correttamente almeno uno tra product_attributes e product_image.

Ad esempio, la pubblicazione di questo post genererà un errore.

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

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

Per generare suggerimenti di testo, è necessario almeno un campo di product_info

Questo errore

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

indica che devi includere almeno un campo product_info nel corpo della richiesta.

Ad esempio, la pubblicazione di questo post genererà un errore.

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

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

Utilizza invece qualcosa come

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

(Something) is required in each title_example

Errori come i seguenti quattro esempi

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

indicano che non hai compilato un sottocampo obbligatorio.

Ad esempio, la seguente richiesta genererebbe un errore.

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

Per risolvere il problema, per ogni title_example specificato nella richiesta, compila tutti i seguenti campi secondari:

product_info
category
title_format
final_product_info

Ecco un esempio che funziona:

{
   "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 non supportato

Questo tipo di errore

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

risulterebbe da una richiesta come

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 richiesta imposta workflow_id su "attributi", ma questo campo supporta solo uno dei seguenti valori:

title: genera o ottimizza il titolo del prodotto.
description: genera o ottimizza la descrizione del prodotto.
tide: genera o ottimizza sia il titolo che la descrizione del prodotto.

Tono non supportato

Un errore "Tono non supportato", ad esempio

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

risulterebbe da una richiesta come

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

Tieni presente che tone è impostato su "allegro", ma questo campo supporta solo uno dei seguenti valori:

default: semplice, chiaro ed elegante.
Giocoso: spensierato, con un linguaggio positivo, umorismo (battute, giochi di parole) ed esagerazione (senza ironia, sarcasmo o emoji).
Formale: inglese standard, grammatica corretta, frasi complete, nessun slang o contrazioni.
persuasivo: logico, conciso e basato su argomentazioni per convincere il lettore.
Conversazionale: linguaggio amichevole, facile da capire e di uso quotidiano.

Generare suggerimenti di testo Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Cosa puoi generare utilizzando l'API?

Guida rapida

Esempi

Generazione di titoli ottimizzati

Richiesta

Risposta

Generare un titolo solo da un'immagine

Richiesta

Risposta

Generare un titolo da una descrizione

Richiesta

Risposta

Ottimizzare i titoli da un titolo e una descrizione (insieme a un esempio personalizzato)

Richiesta

Risposta

Generare una descrizione da un titolo

Richiesta

Risposta

Generare un titolo e una descrizione a partire dagli attributi del prodotto (come marca e colore)

Richiesta

Risposta

Supporto delle lingue di destinazione

Valori di esempio:

Esempio di richiesta

Risposta

Personalizzazione del tono di voce per la generazione di descrizioni

Librerie client

Esempi di codice

Java

Errori e problemi comuni

Per generare suggerimenti di testo sono necessarie le informazioni sul prodotto

Per generare suggerimenti di testo, è necessario almeno un campo di product_info

(Something) is required in each title_example

workflow_id non supportato

Tono non supportato

Generare suggerimenti di testo