Generare suggerimenti di testo

L'API Text Suggestions sfrutta gli strumenti di AI generativa dell'API Product Studio per generare e ottimizzare i titoli e le descrizioni dei prodotti. Puoi utilizzarlo per migliorare il coinvolgimento e le conversioni dei clienti.

Cosa puoi generare utilizzando l'API?

  • Titoli e descrizioni dei prodotti suggeriti in base soltanto all'immagine del prodotto
  • Titoli ottimizzati per la SEO per i tuoi prodotti
  • Titoli formattati in modo personalizzato per i tuoi prodotti
  • Descrizioni dei prodotti del tuo feed dei prodotti

Puoi anche specificare il tono delle descrizioni.

Per ulteriori informazioni, vedi Abilitazione di un'API nel progetto Google Cloud.

Guida rapida

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

L'API accetta:

  • Attributi prodotto (dizionario JSON): un oggetto JSON contenente gli attributi del prodotto (ad es. {"title": "White Tee", "brand": "MyBrand", "size": "XL"})
  • Immagine prodotto:un URI che rimanda all'immagine del prodotto (ad es. {"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: guarda 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 da diversi input di dati di prodotto. Vengono inoltre presentati 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 di struttura della richiesta:

POST https://merchantapi.googleapis.com/productstudio/v1beta/{name=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": "attributes"
   }
}

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 del prodotto e generare un titolo ottimale.

Richiesta

POST https://merchantapi.googleapis.com/productstudio/v1beta/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/v1beta/{name=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 (oltre all'esempio personalizzato)

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

Richiesta

POST https://merchantapi.googleapis.com/productstudio/v1beta/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 corrispondente.

Richiesta

POST https://merchantapi.googleapis.com/productstudio/v1beta/{name=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 dagli attributi del prodotto (ad esempio marca e colore)

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

Richiesta

POST https://merchantapi.googleapis.com/productstudio/v1beta/{name=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)

Richiesta di esempio

POST https://merchantapi.googleapis.com/productstudio/v1beta/{name=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 stabilire il tuo brand e differenziare il tuo negozio online da altri, puoi personalizzare il tono 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.
    • Allegro: spensierato, con un linguaggio positivo, umoristico (battute, giochi di parole) e esagerato (nessuna ironia, sarcasmo o emoji).
    • Forma: inglese standard, grammatica corretta, frasi complete, niente slang o contrazioni.
    • Persuasiva: logica, concisa e basata su argomentazioni per convincere il lettore.
    • Stile colloquiale: linguaggio amichevole, facile da capire e di uso quotidiano.
  • Tono specifico del brand:puoi fornire descrizioni esistenti o altri asset di testo nel tono di voce 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 concise, molto verbose)
    • Tono (ad esempio professionale, informativo, positivo, persuasivo)
    • Struttura della frase (ad es. "frase semplice con poche connessioni")
    • Parole e frasi più frequenti utilizzate

Errori e problemi comuni

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

Le informazioni sul prodotto sono necessarie per generare suggerimenti di testo

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 o product_image.

Ad esempio, la pubblicazione di questo messaggio comporterà un errore.

POST https://merchantapi.googleapis.com/productstudio/v1beta/{name=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 messaggio causerebbe un errore.

POST https://merchantapi.googleapis.com/productstudio/v1beta/{name=accounts/{ACCOUNT_ID}:generateProductTextSuggestions

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

Utilizza invece qualcosa del tipo

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

o

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

(Something) è obbligatorio in ogni title_example

Errori come i quattro esempi riportati di seguito

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

o

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

o

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

o

{
  ...
    "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 genererà un errore.

POST
https://merchantapi.googleapis.com/productstudio/v1beta/{name=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 titolo_esempio 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",
 ...
}

deriverebbe da una richiesta come

POST https://merchantapi.googleapis.com/productstudio/v1beta/{name=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 "attributes", ma questo campo supporta solo uno tra i 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",
 ...
}

deriverebbe da una richiesta come

POST https://merchantapi.googleapis.com/productstudio/v1beta/{name=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 viene impostato su "allegro", ma questo campo supporta solo uno tra i seguenti valori:

  • default: semplice, chiara ed elegante.
  • Spensierati: con un tono allegro, che utilizza un linguaggio positivo, umoristico (barzellette, giochi di parole) e esagerato (senza ironia, sarcasmo o emoji).
  • formale: inglese standard, grammatica corretta, frasi complete, niente slang o contrazioni.
  • Persuasiva: logica, concisa e basata su argomentazioni per convincere il lettore.
  • colloquiale: linguaggio colloquiale, amichevole e facile da comprendere.