# Cookbook

You can use our API to generate product titles and descriptions using whatever
product information you have available. The API accepts:

- An optional JSON dictionary containing your product attributes. e.g., `{"brand": "MyBrand", "title": "White Tee", "size": "XL"}`.
- An optional product image. e.g., `{"uri": "https://my-store.com/img/1.png"}`.
- Title formatting options. e.g., `attribute_separator`, `target_language`, `attribute_order`.
- Data labelling examples. (seen below)

### First set up your prerequisites.

    import requests
    API_KEY=""
    API_ENDPOINT=""

## Speed up product creation by getting suggested titles from only an image.

    my_product_image = 'https://cdn.shopify.com/s/files/1/0653/5879/0892/products/1672082339438_550x825.jpg?v=1672082415'

    payload = {}
    payload |= {'output_spec': {'workflow_id': 'title', 'attribute_separator': '-'}}
    payload |= {'product_info':{}}
    payload['product_info'] |= {'product_image':{'uri': my_product_image}}

    response = requests.post(API_ENDPOINT, params={'key': API_KEY}, json=payload)
    suggested_title = response.json()['title']['text']
    print(suggested_title)

    Rustic Ceramic & Leather Leaves Necklace

## Speed up product creation by getting suggested titles from a description.

If your product creation flow prompts the user for an image and a brief
description, you can use the following pattern to suggest them a product title.

    my_product_description = 'selling size 12 nike dunks. oh they are red by the way!'

    payload = {}
    payload |= {'output_spec': {'workflow_id': 'title'}}
    payload |= {'product_info':{'product_attributes': {'description': my_product_description}}}

    response = requests.post(API_ENDPOINT, params={'key': API_KEY}, json=payload)
    print(response.json()['title']['text'])

    Nike Dunks Red Size 12

## Speed up product creation by getting suggested titles from a title and description.

In this example, we explicitly label the product attributes we want the AI to
identify.

    title = 'Volumizing & Lengthening Mascara - Dark Brown'
    description = "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging."

    payload = {}
    payload |= {'output_spec': {'workflow_id': 'title'}}
    payload |= {'product_info':{'product_attributes': {'title': title, 'description': description, 'brand': 'Luxe Beauty'}}}
    payload |= {
      "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"
          }
        }
      ]
    }

    response = requests.post(API_ENDPOINT, params={'key': API_KEY}, json=payload)
    print(response.json())

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

## Speed up product creation by getting suggested descriptions from a title.

If your product creation flow prompts the user for an image and a title, you can
use the following pattern to suggest them a product description.

    my_product_title = 'Rustic Ceramic & Leather Leaves Necklace'

    payload = {}
    payload |= {'output_spec': {'workflow_id': 'description'}}
    payload |= {'product_info':{'product_attributes': {'title': my_product_title}}}

    response = requests.post(API_ENDPOINT, params={'key': API_KEY}, json=payload)
    print(response.json()['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.

## Speed up product creation by getting both a title and a description from a brand and color.

Notice how in this example we set `workflow_id` to `"tide"` to get both title
and description.

    payload = {}
    payload |= {'output_spec': {'workflow_id': 'tide'}}
    payload |= {'product_info':{'product_attributes': {'brand': 'Mr. Beast', 'color': 'purple'}}}
    payload['product_info'] |= {'product_image':{'uri':'https://mrbeast.store/cdn/shop/files/0015dlv_0000_327.jpg?v=1702754475&width=500'}}

    response = requests.post(API_ENDPOINT, params={'key': API_KEY}, json=payload)
    print(response.text)

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

### Target Language Support

This field specifies the language of the description text generated in the API
response. It is added as part of the output_spec parameters.

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

Example Values:

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

Example JSON for payload

    title = "Granos de café negro"
    description = "Los granos de café negro en California"

    payload = {}
    payload |= {"output_spec":
      {
        "workflow_id": "description",
        "target_language":"japanese", # specify language here
        "attribute_order": ["scent", "product"],
        "tone":"playful"}
    }
    payload |= {"product_info":{"product_attributes": {"description": description, "brand": "Parfums de Paris", "scent": "Floral"}}}

Example Output

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

> [!NOTE]
> **Note:** The user should specify `target_language` to match their provided examples. As seen in the previous example, although the description was provided for Japanese the title remained in Spanish.

Entering an incorrect language code may result in an error.

If the language or value is not supported, the description text will default to
English.

### Tone of Voice Personalization for Description Generation

To help establish your brand and differentiate your online store from others,
you can personalize the tone of voice of your generated descriptions.
The Text API offers two options:

You can select from a list of tones to generate new descriptions. The list
includes these tone styles:

- Default
- Playful
- Formal
- Persuasive
- Conversational

You can provide existing descriptions or other text assets in your brand's tone
of voice. The LLM will analyze the tone of the text and generate a "writing
style descriptor" according to these aspects:

- Formality (e.g., formal, casual)
- Verbosity (e.g., concise, very verbose)
- Tone (e.g., professional, informative, positive, persuasive)
- Sentence structure (e.g., "simple sentence with few conjunctions")
- Most frequent words and phrases used