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

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

מה אפשר ליצור באמצעות ה-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"
   }
}

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

השגיאה הזו

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

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