The format of a content generation request is shown below. This request shows how to generate a blog with the title "A blog about hats", using British English and the GPT-4o AI model. The request also specifies brand voice, audience and tone of voice.
mutationSubmitContentGenerationJob{ submitContentGenerationJob( input:{ briefTemplateId:"Q29udGVudEdlbmVyYXRpb25CcmllZlRlbXBsYXRlOmJsb2c=" content:{ briefInputs:"{\"brandVoice\":\"Q29udGVudEdlbmVyYXRpb25CcmFuZFZvaWNlOjJkN2QwMGUzLWJiODgtNDVhZS1iNzFkLWFiYjRhMmU2OGY0MA==\",\"audience\":\"Q29udGVudEdlbmVyYXRpb25BdWRpZW5jZTo5MzEwYjAzMS1jOTE0LTRkOTgtODdkOC1kNGUxZGRjYWUxNDk=\",\"tone\":\"Q29udGVudEdlbmVyYXRpb25Ub25lOmVjNzZmOTk2LTc4YzItNGMzNC05ZTYxLTg3YTI2NjllMzQ2Mw==\",\"locale\":\"British English\",\"title\":\"A blog about hats\"}" modelId:"Q29udGVudEdlbmVyYXRpb25Nb2RlbDpmY2E3ZTUzNS00YmE1LTRlODQtODkzYy0xMDg0YWM1ZGM0NDU=" } hubId:"Q01TSHViOm9yZ19QVUI0OU51NDF2eU4zanZQLzVjZjY3OTI0NGNlZGZkMDAwMTA5ZDJlZg==" organizationId:"T3JnYW5pemF0aW9uOm9yZ19QVUI0OU51NDF2eU4zanZQ" } ){ id status{ code } } }
Content generation uses Amplience Credits
A content generation job will use Amplience Credits. If you do not have sufficient credits to complete the job then an error will be returned. See credit usage for an example of how to get your credit balance.
For each content generation job you will need to include:
The organization id
The hub id
The brief template id
content
The content object must include the id of the AI model to be used to generate the content. It also requires the briefInputs, the fields of this object will be specific to the brief template used, should be sent as string of encoded JSON and will usually include fields such as ‘title’, ‘product name’ and ‘product features’. The specific fields for each brief template can be found in the inputSchema field of the template. See brief templates for an example query that returns this information for each template.
The organization id links to your account and ensures you have the Amplience credits you'll need to generate content.
You can find your organization by logging in to the API playground and running the following query. You will need to be an organization admin to run this request.
The organization id will be returned in the response.
query{ viewer{ organizations{ edges{ node{ id name } } } } }
You will need the hub id to find other information that you can include in content generation requests, to return the brand voices or audiences that are configured on a hub, for example.
querygetHubs{ viewer{ organizations{ edges{ node{ cmsHubs{ id name label } } } } } }
A partial response is shown below, showing the available hubs. This example shows the id of the "documentation" hub which we'll use in the example queries on this page. Replace this id with the id of your own hub.
Using the hub id you can list the brands set up on a hub. To list the brands on Documentation hub we use the following query, setting id to the hub id.
The following query can be used to list the content generation templates that are configured on a hub, including any custom templates you created. inputSchema will return the configuration of each template.
On "Documentation" hub there are the standard templates, together with some custom templates we've set up, including "Women's dresses" and "Running shoes". We've included a partial response below. inputSchema is JSON encoded.
The brief template id must be specified in the content generation request.
The following request uses the blog template and requests a blog about hats, using the GPT4o model and no additional parameters.
To try out this query, replace hubId with the id of your own hub and organizationId with your organization id. The other ids will be the same across all hubs.
mutationSubmitContentGenerationJob{ submitContentGenerationJob( input:{ briefTemplateId:"Q29udGVudEdlbmVyYXRpb25CcmllZlRlbXBsYXRlOmJsb2c=" content:{ briefInputs:"{\"title\":\"A blog about hats\"}" modelId:"Q29udGVudEdlbmVyYXRpb25Nb2RlbDpmY2E3ZTUzNS00YmE1LTRlODQtODkzYy0xMDg0YWM1ZGM0NDU=" } hubId:"Q01TSHViOm9yZ19QVUI0OU51NDF2eU4zanZQLzVjZjY3OTI0NGNlZGZkMDAwMTA5ZDJlZg==" organizationId:"T3JnYW5pemF0aW9uOm9yZ19QVUI0OU51NDF2eU4zanZQ" } ){ id status{ code } } }
An example of a completed job is shown below, in this case it's the content generated for the blog we requested.
{ "data":{ "node":{ "id":"Q29udGVudEdlbmVyYXRpb25Kb2I6ODE2NDEyNzAtNmRiZS00NThhLWFkNzEtYzljNjNlNTA5ZWRh", "status":{ "code":"COMPLETE", "message":null }, "content":"{\"body\":\"# Crown Yourself: The Timeless Magic of Hats\\n\\nStep into the world of hats, where every brim, bow, and bobble tells a story. From the sun-drenched beaches to the hallowed halls of fashion’s most prestigious runways, hats have crowned heads and elevated outfits for centuries. They are more than just accessories; they are icons of style, statements of identity, and shields from both the elements and the ordinary.\\n\\n## The History Under the Hat\\n\\nHats have been around for thousands of years, each era imbuing them with its own unique flair. Picture the simple, yet functional straw hats of ancient Egypt, shading both farmers and pharaohs from the relentless sun. Fast forward to the opulence of the 18th century, where powdered wigs were topped with extravagant creations, heightening the grandeur of the aristocracy.\\n\\nIn more recent history, the roaring 20s brought forth the cloche hat, a snug fit symbolic of the flapper’s bold spirit and a refusal to conform. The 60s saw the pillbox hat, epitomized by Jacqueline Kennedy, a chic nod to modern elegance. Each style reflects the zeitgeist of its time, a wearable piece of history.\\n\\n## The Power of a Good Hat\\n\\nA hat is transformative. Slip on a fedora, and you're suddenly channeling old Hollywood glamour. A beret? Instantly, you’re imbued with an air of Parisian nonchalance. Hats have the uncanny ability to change not just how you look, but how you feel. They can be a cloak of confidence or a gateway to a new persona.\\n\\nLet’s not forget their functional prowess. Whether it’s a wide-brimmed sun hat offering respite on a scorching summer day or a cozy beanie warding off winter’s chill, hats provide protection as much as they do panache.\\n\\n## The Hat as a Statement\\n\\nToday, hats remain potent symbols in the fashion world. A bold, oversized hat can turn heads at a race day or a garden party, while a simple baseball cap can speak volumes about personal style or allegiance. In the realm of design, they are a playground for creativity, with designers pushing boundaries to craft stunning headpieces that are both art and accessory.\\n\\n## Conclusion\\n\\nIn the end, a hat is more than just a piece of clothing. It is an expression, a companion, a piece of art perched atop your head. So, the next time you reach for your favorite hat, remember: you’re not just wearing it; you’re wearing a story, a statement, a slice of history. So, go ahead—crown yourself.\"}" } } }
Example with brand voice, audience and tone of voice
The following request extends the blog content generation request and includes brand voice, audience, tone of voice and locale in briefInputs. We've also included fields specific to the product description template, including maximum word count, product features and images. We've specified a brand voice of Anya Finn, an audience of luxury travellers and a tone of voice of humorous and witty to be used to generate the content.
To try out this query, replace hubId with the id of your own hub and organizationId with your organization id. The other ids will be the same across all hubs.
mutationSubmitContentGenerationJob{ submitContentGenerationJob( input:{ briefTemplateId:"Q29udGVudEdlbmVyYXRpb25CcmllZlRlbXBsYXRlOmJsb2c=" content:{ briefInputs:"{\"brandVoice\":\"Q29udGVudEdlbmVyYXRpb25CcmFuZFZvaWNlOjJkN2QwMGUzLWJiODgtNDVhZS1iNzFkLWFiYjRhMmU2OGY0MA==\",\"audience\":\"Q29udGVudEdlbmVyYXRpb25BdWRpZW5jZTo5MzEwYjAzMS1jOTE0LTRkOTgtODdkOC1kNGUxZGRjYWUxNDk=\",\"tone\":\"Q29udGVudEdlbmVyYXRpb25Ub25lOmVjNzZmOTk2LTc4YzItNGMzNC05ZTYxLTg3YTI2NjllMzQ2Mw==\",\"locale\":\"British English\",\"title\":\"A blog about hats\"}" modelId:"Q29udGVudEdlbmVyYXRpb25Nb2RlbDpmY2E3ZTUzNS00YmE1LTRlODQtODkzYy0xMDg0YWM1ZGM0NDU=" } hubId:"Q01TSHViOm9yZ19QVUI0OU51NDF2eU4zanZQLzVjZjY3OTI0NGNlZGZkMDAwMTA5ZDJlZg==" organizationId:"T3JnYW5pemF0aW9uOm9yZ19QVUI0OU51NDF2eU4zanZQ" } ){ id status{ code } } }
The generated content reflects the brand voice, audience and tone of voice we included in the request.
{ "data":{ "node":{ "id":"Q29udGVudEdlbmVyYXRpb25Kb2I6YjM4MjEzOTMtNzFmNC00OGJlLTlkOGYtMTRjYjc0M2Q1YTZj", "status":{ "code":"COMPLETE", "message":null }, "content":"{\"body\":\"# Hat's Off to You: The Topper Talk for Your Travels\\n\\nLadies and gents, lend me your ears and, more importantly, your heads, as we embark on a whimsical journey across the marvellous world of hats. Whether you're jet-setting to the glamorous boulevards of Paris or embarking on a sun-soaked safari, one thing remains true: a well-chosen hat is your crowning glory. \\n\\nPicture this: You're in the bustling streets of Marrakech, and while the air is filled with spices, your hair is filled with... frizz. Fear not, your trusty Panama hat is here to save the day, shading you from the sun, while adding a touch of suave to your saunter. Who needs a magic carpet when you've got a hat that turns heads?\\n\\nNext, let's swan dive into the Riviera, where the sun smiles brightly, and a wide-brimmed straw hat is your passport to Riviera chic. It's not just a hat; it's your portable piece of shade, doubling as the perfect shield when your ex decides to make an unscheduled cameo appearance in Saint-Tropez.\\n\\nBut wait, there's more! For those of you with a penchant for the unpredictable British weather, the classic flat cap is your best mate. Rain or shine, this adaptable accessory will keep you looking dapper while you navigate the cobbled streets of London. Just remember to tip your cap to the Beefeaters as you pass by.\\n\\nNow, I know what you're thinking. \\\"What about those windswept hills in the Scottish Highlands?\\\" Enter the beret, the hat that says, \\\"I'm here for the haggis, but I'll take the whisky too.\\\" It's the quintessential accessory for when you're feeling both Bonnie and Clyde.\\n\\nSo, dear luxury travellers, remember this: a hat is not merely an accessory; it’s an adventure in itself. It’s your confidant, your shield, and your stylish companion on the road less travelled. So, next time you're packing your bags, give your hat collection a nod – because every great journey deserves a great hat.\\n\\nAnd as you tip your hat to the world, may your travels be as grand as your taste in headwear. Hat's all, folks!\"}" } } }
The following example shows how to generate content using the product description template and includes images as part of the inputs to the request. The request defines input using a GraphQL variable.
For each image included in a request you need to specify an id, in this example a random UUID, and the image URL. The id is not validated so you can use any unique value. The URL must be an Amplience domain, either a Content Hub URL, or uploaded using the temporary file service.
To try out this query, replace hubId with the id of your own hub and organizationId with your organization id. The other ids will be the same across all hubs.
mutationsubmitContentGenerationJob($input:SubmitContentGenerationJobInput!){ submitContentGenerationJob(input:$input){ id } }
Add the following to the variables section of the request. We have specified 3 images to be used as part of the content generation request.
And here's an example of the generated product description content.
{ "data":{ "node":{ "id":"Q29udGVudEdlbmVyYXRpb25Kb2I6NDU4YWFjYmYtYThjZi00MzI5LWEzYTItMDdiNTNhMDhiZDA5", "status":{ "code":"COMPLETE", "message":null }, "content":"{\"description\":\"Embark on your next adventure with the Big Adventure hiking boots, designed to support every step of your journey. These rugged boots offer unmatched comfort and durability, perfect for hiking enthusiasts and casual walkers alike. Whether you're trekking through rocky landscapes or enjoying a peaceful walk in the woods, these boots provide the reliability and support you need. They are a great value for fitness enthusiasts looking to combine style with functionality. The sturdy construction ensures they withstand the rigors of any terrain, making them an essential part of your adventure gear.\\n\\n- Rugged design for durability\\n- Comfortable fit for extended wear\\n- Excellent value for hiking and walking\\n- Ideal for outdoor adventures and fitness activities\"}" } } }
You can submit up to 5 content generation jobs as part of one request as shown below.
mutationsubmitContentGenerationJobs($input1:SubmitContentGenerationJobInput!,$input2:SubmitContentGenerationJobInput!){ job1:submitContentGenerationJob(input:$input1){ id } job2:submitContentGenerationJob(input:$input2){ id } }
For this example include input1 and input2 in the variables section of the request.
Replace organizationId and hubId with your own organization id and the id of the hub you're using.
{ "input1":{ "organizationId":"T3JnYW5pemF0aW9uOm9yZ19QVUI0OU51NDF2eU4zanZQ", "hubId":"Q01TSHViOm9yZ19QVUI0OU51NDF2eU4zanZQLzVjZjY3OTI0NGNlZGZkMDAwMTA5ZDJlZg==", "briefTemplateId":"Q29udGVudEdlbmVyYXRpb25CcmllZlRlbXBsYXRlOmJsb2c=", "content":{ "briefInputs":"{\"title\":\"Write a blog about cats\"}", "modelId":"Q29udGVudEdlbmVyYXRpb25Nb2RlbDpmY2E3ZTUzNS00YmE1LTRlODQtODkzYy0xMDg0YWM1ZGM0NDU=" } }, "input2":{ "organizationId":"T3JnYW5pemF0aW9uOm9yZ19QVUI0OU51NDF2eU4zanZQ", "hubId":"Q01TSHViOm9yZ19QVUI0OU51NDF2eU4zanZQLzVjZjY3OTI0NGNlZGZkMDAwMTA5ZDJlZg==", "briefTemplateId":"Q29udGVudEdlbmVyYXRpb25CcmllZlRlbXBsYXRlOmJsb2c=", "content":{ "briefInputs":"{\"title\":\"Write a blog about the role of mice in history\"}", "modelId":"Q29udGVudEdlbmVyYXRpb25Nb2RlbDpmY2E3ZTUzNS00YmE1LTRlODQtODkzYy0xMDg0YWM1ZGM0NDU=" } } }
The generated content is returned in the response. In this case the 2 blog posts we requested.
{ "data":{ "node1":{ "id":"Q29udGVudEdlbmVyYXRpb25Kb2I6ZDg4OTA4MDItZTcyNy00OTgyLWE5NjUtZDEzNGMwZmM5NjRl", "status":{ "code":"COMPLETE", "message":null }, "content":"{\"body\":\"# The Enigmatic World of Cats: A Purrfectly Fascinating Journey\\n\\nAh, the captivating allure of cats! These elegant creatures have been weaving their mysterious charm into the fabric of human history for thousands of years. From the sacred temples of ancient Egypt to the cozy corners of our modern homes, cats have always maintained an air of mystery that keeps us utterly enchanted.\\n\\n**The Feline Mystique**\\n\\nWhat is it about cats that leaves us so spellbound? Perhaps it's their graceful movements—a dance of elegance and agility that seems almost otherworldly. Or maybe it's their piercing eyes, which speak volumes without uttering a single sound. Cats, with their independent spirits and strong personalities, are a paradox; aloof yet affectionate, wild yet domesticated.\\n\\n**From Myth to Modernity**\\n\\nThroughout history, cats have been both revered and misunderstood. In ancient Egypt, they were worshipped as deities, believed to be the embodiment of the goddess Bastet, protector of the home and family. Fast forward to the Middle Ages, and cats found themselves embroiled in superstition, often unfairly linked to witchcraft and dark magic.\\n\\nToday, cats have shed their mystical cloaks (mostly) and found their place as beloved companions in our lives. They have a unique ability to adapt, whether they're prowling the urban jungle or lounging on a sun-drenched windowsill. Yet, despite their prevalence in our world, they have not lost that enigmatic aura that makes them so intriguing.\\n\\n**The Language of Cats**\\n\\nCats communicate in a language all their own—a symphony of purrs, meows, and body language. A slow blink from a cat is a tender gesture, a sign of trust and affection. Meanwhile, a twitching tail might signal excitement, irritation, or curiosity. Learning to understand these subtle cues can deepen the bond between human and feline, transforming a simple pet into a cherished friend.\\n\\n**The Cat Effect**\\n\\nStudies suggest that living with cats can have positive effects on our health. Their gentle purring can lower stress levels and even help reduce blood pressure. In essence, cats are not just pets; they are tiny therapists with fur, offering comfort through their presence and companionship.\\n\\nIn a world that often feels overwhelming, the serene presence of a cat can offer solace. They remind us to slow down, to appreciate the small moments, and to find joy in the quiet beauty of life. So, whether you're a seasoned cat lover or just beginning to explore the world of whiskers and purrs, embrace the mystery and magic that is the feline world. After all, life is simply better with a cat by your side.\"}" }, "node2":{ "id":"Q29udGVudEdlbmVyYXRpb25Kb2I6ZDA2MTc1ZTctODY1Yi00ZWY3LTg1ZTUtMjhmZTFlNTBhZGMx", "status":{ "code":"COMPLETE", "message":null }, "content":"{\"body\":\"# Whiskered Witnesses: The Role of Mice in the Tapestry of History\\n\\nIn the grand annals of history, where empires rise and fall and heroes are born and fade, tiny creatures often scuttle beneath the radar of human attention. Among these unsung participants are mice, the diminutive rodents whose influence and presence have quietly woven through the fabric of our past. From the dark corners of medieval castles to the bustling laboratories of modern science, mice have played roles both surprising and significant.\\n\\n## Medieval Mischief Makers\\n\\nPicture this: a medieval feast, tables groaning under the weight of delectable fare, and lords and ladies clad in finery. Beneath the floorboards, however, an unseen drama unfolds. Mice, ever the opportunists, scuttle about, nibbling on crumbs and leftovers. Their presence was not merely a nuisance; it was a reminder of the necessity for cleanliness and food storage that helped shape domestic practices. The mice of medieval times, in their relentless quest for sustenance, indirectly influenced the evolution of hygiene standards, driving humans toward better living conditions.\\n\\n## Scientific Pioneers\\n\\nLeap forward to the era of enlightenment and discovery, and you'll find mice at the forefront of scientific advancement. These small creatures became indispensable to research, their genetic proximity to humans making them ideal candidates for experimentation. From understanding genetics to unraveling the mysteries of disease, mice have been silent yet crucial partners in laboratories. The humble mouse has been instrumental in groundbreaking discoveries, including the development of vaccines and treatments that have saved countless lives.\\n\\n## Cultural Symbols\\n\\nBeyond their tangible contributions, mice have scuttled into the realms of culture and mythology. From the clever mouse in Aesop's fables to the beloved characters in literature and film, these creatures have captured our imagination. They have symbolized everything from resourcefulness to pestilence, their duality reflecting the complex relationship humans have with nature.\\n\\n## Modern-Day Heroes\\n\\nToday, mice continue to play pivotal roles in the advancement of science and medicine. Genetic engineering has transformed them into living models for human disease, providing insights that guide medical breakthroughs. In the world of technology, robotic mice are even being used to explore and map hazardous environments, showcasing their adaptability and enduring relevance.\\n\\nIn the grand narrative of history, mice may not have wielded swords or forged treaties, but their quiet contributions have been nothing short of monumental. As we continue to unravel the mysteries of our past and innovate for the future, let us not forget these whiskered witnesses, whose tiny footprints have left an indelible mark on the story of humanity.\"}" } } }
Submit a content generation request, specifying values for the fields you've defined for your template
Poll for the response
Custom templates have an "additional instructions" section that should include a detailed prompt specifying how content should be generated. You do not need to specify this in the content generation request, it will be read from the template and sent as part of each request. Note that you can't currently specify brand voice, audience or tone of voice, so this will need to be included as guidance to the model in the "additional instructions" section of the template.
The following example shows how to generate content from the "Running shoe" custom template. This has a template id of Q29udGVudEdlbmVyYXRpb25CcmllZlRlbXBsYXRlOjEyZjNkNWFiLTliMmUtNDg2Ny05Y2YyLThhZTdiNDliNzk4OA==.
We have just specified the title. The instructions are taken from the template and used with each content generation.
To send a request using your own custom template, replace briefTemplateId with the id of your own template, organizationId with your own organization id and hubId with the id of your own hub.
As with other content generation requests, the response to SubmitContentGenerationJob will contain the id that you will use to poll for the generated content.
Here's an example of a completed job, with content generated from our custom template and using the "additional instructions" defined in the custom template.
{ "data":{ "node":{ "id":"Q29udGVudEdlbmVyYXRpb25Kb2I6MzFjYzNkMjgtN2Y4Mi00MWZmLTlmZjUtOTQ2ZWY1NjM1MGZi", "status":{ "code":"COMPLETE", "message":null }, "content":"{\"content\":\"**The Rugged Outdoor Shoe - Forest Green**\\n\\nStep out and conquer any trail with The Rugged Outdoor Shoe in Forest Green, designed to elevate your outdoor adventures with unmatched comfort and durability. Whether you're tackling steep inclines or navigating rocky paths, these shoes provide the perfect balance of support and flexibility to keep you steady on your feet.\\n\\n- **Product Specifications:**\\n - **Durable Construction:** Crafted with high-quality materials to withstand rough terrains.\\n - **Enhanced Traction:** Non-slip rubber soles grip firmly to diverse surfaces.\\n - **Breathable Design:** Mesh upper allows for optimal airflow, keeping your feet cool and dry.\\n - **Comfortable Fit:** Cushioned insoles mold to your feet for all-day comfort.\\n - **Water-Resistant Finish:** Keeps your feet dry during unexpected weather changes.\\n \\nWith a design that blends functionality with style, these running shoes are your perfect companion for any outdoor escapade. Lace up your new favorite pair today and turn every trail into an exhilarating journey!\"}" } } }
The following query shows how to get the name and label for the input fields configured in a template, in this case the "Running shoe" custom template. Change the id to the id of the template that you want to return.