Esta página foi traduzida pela API Cloud Translation.

Gerar sugestões de texto

A API Text Suggestions usa as ferramentas de IA generativa da API Product Studio para gerar e otimizar títulos e descrições de produtos. Você pode usar esse recurso para melhorar o engajamento e a conversão dos clientes, além de simplificar o processo de gerenciamento e atualização das informações de produtos. Os recursos da API Product Studio podem ajudar você a otimizar sua performance no varejo.

O que é possível gerar usando a API?

A API Text Suggestions ajuda você a fazer o seguinte:

Títulos e descrições de produtos sugeridos com base na imagem e/ou nos atributos do item.
Títulos otimizados para SEO dos seus produtos
Títulos formatados de maneira personalizada para seus produtos
Descrições de produtos do seu feed de produtos

Você também pode especificar o tom de voz das descrições e manter a consistência em todas as informações de produtos.

Guia de início rápido

O método GenerateProductTextSuggestions pode gerar ou otimizar títulos e descrições de produtos usando suas informações de produtos.

A API aceita:

Atributos do produto (dicionário JSON): um objeto JSON que contém atributos do produto (como {"title": "White Tee", "brand": "MyBrand", "size": "XL"}).
Imagem do produto:um URI que aponta para a imagem do produto (por exemplo, {"uri": "https://my-store.com/img/1.png"})
Opções de formatação de título: parâmetros para personalizar a geração de títulos, incluindo:
- attribute_separator: especifica o separador entre atributos.
- target_language: define o idioma de saída.
- attribute_order: define a ordem dos atributos no título gerado.
Exemplos de rotulagem de dados: veja um exemplo de como Gerar um título com base em uma descrição.
ID do fluxo de trabalho (output_spec.workflow_id): o campo workflow_id no objeto output_spec determina o tipo de geração de texto:
- title: gera ou otimiza o título do produto.
- description: gera ou otimiza a descrição do produto.
- tide: gera ou otimiza o título e a descrição do produto.

Exemplos

Confira exemplos de uso da API para gerar ou otimizar um título ou uma descrição, ou ambos, com base em diferentes entradas de dados de produtos. Também apresentamos Erros e problemas comuns e as soluções deles.

Geração de títulos otimizada

O exemplo mostra como gerar um título ideal.

Solicitação

O corpo da solicitação contém as informações do produto a serem usadas para otimização do título. Confira um exemplo da estrutura de solicitação:

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

Resposta

Você vai receber uma resposta como

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

Gerar um título apenas com uma imagem

O exemplo mostra como fornecer uma imagem do produto e gerar um título ideal.

Solicitação

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

Resposta

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

Gerar um título com base em uma descrição

O exemplo mostra como fornecer uma descrição do produto e gerar um título ideal.

Solicitação

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

Resposta

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

Otimizar títulos com base em um título e uma descrição (além de um exemplo personalizado)

Neste exemplo, rotulamos explicitamente os atributos do produto que queremos que a IA identifique e a ordenação dos atributos na saída.

Solicitação

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

Resposta

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

Gerar uma descrição com base em um título

O exemplo mostra como fornecer um título de produto e pedir à API para gerar uma descrição correspondente.

Solicitação

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

Resposta

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

Gerar um título e uma descrição com base nos atributos do produto (como marca e cor)

Este exemplo demonstra como fornecer atributos de produto para gerar um título e uma descrição ideais.

Solicitação

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

Resposta

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

Suporte a idiomas de destino

Esse campo especifica o idioma do texto de descrição gerado na resposta da API. Você pode adicionar o target_language como parte dos parâmetros output_spec:

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

Exemplos de valores:

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

Exemplo de solicitação

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

Resposta

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

Personalização do tom de voz para geração de descrições

Para ajudar a estabelecer sua marca e diferenciar sua loja on-line de outras, personalize o tom de voz das descrições geradas. A API Text oferece duas opções:

Seleção de tom predefinido:você pode escolher em uma lista de tons para gerar novas descrições. A lista inclui estes estilos de tom:
- Padrão:simples, claro e elegante.
- Divertido:leve, usando linguagem positiva, humor (piadas, trocadilhos) e exagero (sem ironia, sarcasmo ou emojis).
- Formal:inglês padrão, gramática correta, frases completas, sem gírias ou contrações.
- Persuasivo:lógico, conciso e baseado em argumentos para convencer o leitor.
- Conversacional:linguagem amigável, fácil de entender e do dia a dia.
Tom específico da marca:você pode fornecer descrições ou outros recursos de texto no tom de voz da sua marca. O modelo de IA generativa vai analisar o tom do texto e gerar um "descritor de estilo de escrita" de acordo com estes aspectos:
- Formalidade (por exemplo, formal, informal)
- Verbosidade (por exemplo, concisa, muito prolixa)
- Tom (por exemplo, profissional, informativo, positivo, persuasivo)
- Estrutura da frase (por exemplo, "frase simples com poucas conjunções")
- Palavras e frases mais usadas

Bibliotecas de cliente

Recomendamos que você use bibliotecas de cliente para enviar suas solicitações. Vamos compartilhar as bibliotecas de cliente com você, que podem ser instaladas no seu projeto Maven.

Amostras de código

Escolha seu método de autenticação e configure estes exemplos de código usando estas instruções. Confira um exemplo que você pode usar para gerar sugestões de texto.

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

Erros e problemas comuns

Confira alguns problemas comuns e as soluções deles.

As informações do produto são necessárias para gerar sugestões de texto

Se você receber a seguinte mensagem de erro:

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

Adicione product_info no corpo da solicitação e preencha corretamente pelo menos um dos campos product_attributes ou product_image.

Por exemplo, postar isso vai resultar em um erro.

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

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

É necessário ter pelo menos um campo de "product_info" para gerar sugestões de texto

Este erro

{
  "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 que você precisa incluir pelo menos um campo product_info no corpo da solicitação.

Por exemplo, postar isso resultaria em um erro.

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

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

Em vez disso, use algo como

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

(Algo) é obrigatório em cada title_example

Erros como os quatro exemplos a seguir

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

indicar que você não preencheu um subcampo obrigatório.

Por exemplo, a solicitação a seguir geraria um erro.

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

Para resolver isso, para cada title_example especificado na solicitação, preencha todos os seguintes subcampos:

product_info
category
title_format
final_product_info

Confira um exemplo que funciona:

{
   "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 não compatível

Esse tipo de erro

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

resultaria de uma solicitação como

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

A solicitação define workflow_id como "attributes", mas esse campo aceita apenas um dos seguintes valores:

title: gera ou otimiza o título do produto.
description: gera ou otimiza a descrição do produto.
maré: gera ou otimiza o título e a descrição do produto.

Tom sem suporte

Um erro de "Tom sem suporte", como

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

resultaria de uma solicitação como

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

Observe que tone está definido como "alegre", mas esse campo aceita apenas um dos seguintes valores:

padrão: simples, claro e elegante.
Descontraído: leve, usando linguagem positiva, humor (piadas, trocadilhos) e exagero (sem ironia, sarcasmo ou emojis).
formal: inglês padrão, gramática correta, frases completas, sem gírias ou contrações.
Persuasivo: lógico, conciso e baseado em argumentos para convencer o leitor.
Conversacional: linguagem amigável, fácil de entender e cotidiana.

Gerar sugestões de texto Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O que é possível gerar usando a API?

Guia de início rápido

Exemplos

Geração de títulos otimizada

Solicitação

Resposta

Gerar um título apenas com uma imagem

Solicitação

Resposta

Gerar um título com base em uma descrição

Solicitação

Resposta

Otimizar títulos com base em um título e uma descrição (além de um exemplo personalizado)

Solicitação

Resposta

Gerar uma descrição com base em um título

Solicitação

Resposta

Gerar um título e uma descrição com base nos atributos do produto (como marca e cor)

Solicitação

Resposta

Suporte a idiomas de destino

Exemplos de valores:

Exemplo de solicitação

Resposta

Personalização do tom de voz para geração de descrições

Bibliotecas de cliente

Amostras de código

Java

Erros e problemas comuns

As informações do produto são necessárias para gerar sugestões de texto

É necessário ter pelo menos um campo de "product_info" para gerar sugestões de texto

(Algo) é obrigatório em cada title_example

workflow_id não compatível

Tom sem suporte

Gerar sugestões de texto