텍스트 추천 생성

텍스트 추천 API는 Product Studio API의 생성형 AI 도구를 활용하여 제품 제목과 설명을 생성하고 최적화합니다. 이를 사용하여 고객 참여도와 전환을 개선하고 제품 정보 관리 및 업데이트 프로세스를 간소화할 수 있습니다. Product Studio API의 기능을 사용하면 소매업체 실적을 최적화할 수 있습니다.

API를 사용하여 무엇을 생성할 수 있나요?

Text Suggestions API는 다음 작업을 수행하는 데 도움이 됩니다.

  • 제품 이미지 또는 제품 속성을 기반으로 추천 제품명 및 설명이 표시됩니다.
  • 제품의 검색엔진 최적화 제목
  • 제품의 맞춤 형식 제목
  • 제품 피드의 제품 설명

설명의 어조를 지정하고 모든 제품 등록정보에서 일관성을 유지할 수도 있습니다.

빠른 시작

GenerateProductTextSuggestions 메서드는 제품 정보를 사용하여 제품명과 설명을 생성하거나 최적화할 수 있습니다.

API는 다음을 허용합니다.

  • 제품 속성 (JSON 사전): 제품 속성 (예: {"title": "White Tee", "brand": "MyBrand", "size": "XL"})이 포함된 JSON 객체입니다.
  • 제품 이미지: 제품 이미지를 가리키는 URI (예: {"uri": "https://my-store.com/img/1.png"})
  • 제목 서식 옵션: 제목 생성을 맞춤설정하기 위한 매개변수입니다. 여기에는 다음이 포함됩니다.
    • attribute_separator: 속성 간 구분자를 지정합니다.
    • target_language: 출력 언어를 설정합니다.
    • attribute_order: 생성된 제목의 속성 순서를 정의합니다.
  • 데이터 라벨 지정 예: 설명에서 제품명을 생성하는 방법을 보여주는 예시를 확인하세요.
  • 워크플로 ID (output_spec.workflow_id): output_spec 객체 내의 workflow_id 필드는 텍스트 생성 유형을 결정합니다.
    • title: 제품 제목을 생성하거나 최적화합니다.
    • description: 제품 설명을 생성하거나 최적화합니다.
    • tide: 제품명과 설명을 모두 생성하거나 최적화합니다.

예

다음은 API를 사용하여 다양한 제품 데이터 입력에서 제품명 또는 설명 또는 둘 다를 생성하거나 최적화하는 예입니다. 일반적인 오류 및 문제와 해결 방법도 제시합니다.

최적화된 제목 생성

이 예에서는 최적의 제목을 생성하는 방법을 보여줍니다.

요청

요청 본문에는 제품명 최적화에 사용할 제품 정보가 포함되어 있습니다. 요청 구조의 예는 다음과 같습니다.

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

응답

다음과 같은 대답을 받을 수 있습니다.

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

이미지만으로 제목 생성

이 예에서는 제품 이미지를 제공하고 최적의 제품명을 생성하는 방법을 보여줍니다.

요청

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

응답

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

설명에서 제목 생성

이 예시에서는 제품 설명을 제공하고 최적의 제목을 생성하는 방법을 보여줍니다.

요청

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": {
    "text": "Nike Dunks Red Size 12"
  },
  "metadata": {
    "metadata": {
      "attributes": {
        "brand": "Nike",
        "color": "Red",
        "size": "12",
        "product": "Dunks"
      },
    }
  }
}

제목과 설명 (맞춤 예시 포함)에서 제목 최적화

이 예에서는 AI가 식별해야 하는 제품 속성과 출력의 속성 순서를 명시적으로 라벨링합니다.

요청

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

응답

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

제목에서 설명 생성

이 예에서는 제품 제목을 제공하고 API에 해당 제품 설명을 생성하도록 요청하는 방법을 보여줍니다.

요청

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

응답

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

제품 속성 (예: 브랜드 및 색상)에서 제품명과 설명 생성

이 예에서는 제품 속성을 제공하여 최적의 제품 제목과 설명을 생성하는 방법을 보여줍니다.

요청

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

응답

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

대상 언어 지원

이 필드는 API 응답에서 생성된 설명 텍스트의 언어를 지정합니다. target_language을 output_spec 매개변수의 일부로 추가할 수 있습니다.

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

값 예시:

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

요청 예시

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

응답

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

설명 생성을 위한 어조 맞춤설정

브랜드를 구축하고 온라인 상점을 다른 상점과 차별화하기 위해 생성된 설명의 어조를 맞춤설정할 수 있습니다. Text API는 두 가지 옵션을 제공합니다.

  • 사전 정의된 어조 선택: 어조 목록에서 선택하여 새 설명을 생성할 수 있습니다. 목록에는 다음과 같은 어조 스타일이 포함됩니다.
    • 기본값: 단순하고 명확하며 세련됨
    • 장난기 있음: 가벼운 분위기, 긍정적인 언어, 유머 (농담, 말장난), 과장 (반어법, 비꼬는 표현, 그림 이모티콘 없음) 사용
    • 공식: 표준 영어, 올바른 문법, 완전한 문장, 속어나 축약형 없음
    • 설득력: 독자를 설득하기 위해 논리적이고 간결하며 주장을 제시합니다.
    • 대화형: 친근하고 이해하기 쉬운 일상적인 언어
  • 브랜드별 어조: 브랜드의 어조로 기존 설명 또는 기타 텍스트 애셋을 제공할 수 있습니다. 생성형 AI 모델은 텍스트의 어조를 분석하고 다음 측면에 따라 '글쓰기 스타일 설명자'를 생성합니다.
    • 높임말 정도 (예: 격식체, 비격식체)
    • 상세 출력 (예: 간결함, 매우 상세함)
    • 어조 (예: 전문적, 유익함, 긍정적, 설득력 있음)
    • 문장 구조 (예: '접속사가 적은 간단한 문장')
    • 가장 자주 사용되는 단어 및 구문

클라이언트 라이브러리

클라이언트 라이브러리를 사용하여 요청을 제출하는 것이 좋습니다. Maven 프로젝트에 설치할 수 있는 클라이언트 라이브러리가 공유됩니다.

코드 샘플

인증 방법을 선택하고 이 안내에 따라 코드 샘플을 설정합니다. 다음은 텍스트 추천을 생성하는 데 사용할 수 있는 샘플입니다.

자바

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

일반적인 오류 및 문제

다음은 몇 가지 일반적인 문제와 해결 방법입니다.

텍스트 추천을 생성하려면 제품 정보가 필요합니다.

다음 오류 메시지가 표시되면

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

요청 본문에 product_info를 추가하고 product_attributes 또는 product_image 중 하나 이상을 올바르게 채웁니다.

예를 들어 다음과 같이 게시하면 오류가 발생합니다.

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

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

텍스트 추천을 생성하려면 product_info 필드가 하나 이상 필요합니다.

이 오류

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

요청 본문에 하나 이상의 product_info 필드를 포함해야 함을 나타냅니다.

예를 들어 다음과 같이 게시하면 오류가 발생합니다.

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

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

대신 다음과 같은 것을 사용하세요.

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

각 title_example에 (항목)이 필요합니다.

다음 네 가지 예와 같은 오류

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

필수 하위 필드를 입력하지 않았음을 나타냅니다.

예를 들어 다음 요청은 오류를 생성합니다.

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

이 문제를 해결하려면 요청에 지정된 각 title_example에 대해 다음 하위 필드를 모두 채우세요.

  • product_info
  • category
  • title_format
  • final_product_info

다음은 작동하는 예입니다.

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

이 유형의 오류

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

다음과 같은 요청으로 인해

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

요청에서 workflow_id을 'attributes'로 설정했지만 이 필드는 다음 값 중 하나만 지원합니다.

  • title: 제품명을 생성하거나 최적화합니다.
  • description: 제품 설명을 생성하거나 최적화합니다.
  • tide: 제품명과 설명을 모두 생성하거나 최적화합니다.

지원되지 않는 어조

다음과 같은 '지원되지 않는 어조' 오류

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

다음과 같은 요청으로 인해

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

tone이 'cheerful'로 설정되어 있지만 이 필드는 다음 값 중 하나만 지원합니다.

  • default: 심플하고 명확하며 세련됩니다.
  • 장난기 있는: 가벼운 마음으로 긍정적인 언어, 유머 (농담, 말장난), 과장 (반어법, 비꼬는 표현, 그림 이모티콘 없음)을 사용합니다.
  • formal: 표준 영어, 적절한 문법, 완전한 문장, 속어나 축약형 없음
  • 설득력 있는: 독자를 설득하기 위해 논리적이고 간결하며 주장을 제시합니다.
  • 대화형: 친근하고 이해하기 쉬운 일상적인 언어