דף זה תורגם על ידי Cloud Translation API.

יצירת הצעות לטקסט

ממשק Text Suggestions API משתמש בכלי ה-AI הגנרטיבי של Product Studio API כדי ליצור ולבצע אופטימיזציה של שמות ותיאורים של מוצרים. אתם יכולים להשתמש בהם כדי לשפר את ההמרות ואת המעורבות של הלקוחות.

מה אפשר ליצור באמצעות ה-API?

הצעות לשמות ולתיאורים של מוצרים על סמך תמונת המוצר ו/או מאפייני המוצר.
שמות מוצרים שעברו אופטימיזציה ל-SEO
שמות של מוצרים בפורמט מותאם אישית
תיאורי מוצרים מפיד המוצרים

אפשר גם לציין את סגנון הדיבור של התיאורים.

מדריך למתחילים

באמצעות השיטה GenerateProductTextSuggestions אפשר ליצור שמות ותיאורים של מוצרים או לבצע אופטימיזציה שלהם על סמך פרטי המוצרים.

ה-API מקבל:

מאפייני המוצר (מילון JSON): אובייקט JSON שמכיל מאפייני מוצרים (למשל, {"title": "White Tee", "brand": "MyBrand", "size": "XL"})
תמונת המוצר: מזהה URI שמפנה לתמונת המוצר (למשל, {"uri": "https://my-store.com/img/1.png"})
אפשרויות עיצוב של כותרות: פרמטרים להתאמה אישית של יצירת הכותרות, כולל:
- attribute_separator: מציין את התו המפריד בין המאפיינים.
- target_language: הגדרת שפת הפלט.
- attribute_order: מגדיר את סדר המאפיינים בכותרת שנוצרת.
דוגמאות לתיוג נתונים: דוגמה ליצירת שם מתיאור.
מזהה תהליך עבודה (output_spec.workflow_id): השדה workflow_id באובייקט output_spec קובע את סוג היצירה של הטקסט:
- 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.

דוגמאות קוד

בוחרים את שיטת האימות ומגדירים את דוגמאות הקוד האלה לפי ההוראות האלה. הנה דוגמה שאפשר להשתמש בה כדי ליצור הצעות לטקסט.

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

שגיאות ובעיות נפוצות

ריכזנו כאן כמה מלכודות נפוצות והפתרונות שלהן.

חובה להזין מידע על המוצר כדי ליצור הצעות לטקסט

אם מופיעה הודעת השגיאה הבאה

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

(Something) נדרש בכל 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', אבל השדה הזה תומך רק באחד מהערכים הבאים:

ברירת מחדל: פשוט, ברור ואלגנטי.
שובב: קל-דעת, עם שפה חיובית, הומור (בדיחות, משחקי מילים) והגזמה (ללא אירוניה, סרקזם או אמוג'י).
רשמית: אנגלית רגילה, דקדוק תקין, משפטים מלאים, ללא שפה מדוברת או קיצורים.
משכנעת: לוגית, תמציתית ומבוססת על טיעונים כדי לשכנע את הקורא.
שיחה: שפה ידידותית וקלה להבנה, שפה יומיומית.

יצירת הצעות לטקסט קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מה אפשר ליצור באמצעות ה-API?

מדריך למתחילים

דוגמאות

יצירת שמות פריטים שעברו אופטימיזציה

בקשה

תשובה

יצירת שם רק מתמונה

בקשה

תשובה

יצירת כותרת מתיאור

בקשה

תשובה

אופטימיזציה של כותרות מכותרת ותיאור (לצד דוגמה מותאמת אישית)

בקשה

תשובה

יצירת תיאור מכותרת

בקשה

תשובה

יצירת שם ותיאור ממאפייני המוצר (כמו מותג וצבע)

בקשה

תשובה

תמיכה בשפת היעד

ערכים לדוגמה:

בקשה לדוגמה

תשובה

התאמה אישית של סגנון הדיבור ליצירת תיאורים

ספריות לקוח

דוגמאות קוד

Java

שגיאות ובעיות נפוצות

חובה להזין מידע על המוצר כדי ליצור הצעות לטקסט

כדי ליצור הצעות טקסט, נדרש לפחות שדה אחד של product_info

(Something) נדרש בכל title_example

workflow_id לא נתמך

טון לא נתמך

יצירת הצעות לטקסט