### Generate asset request examples Source: https://developers.abyssale.com/rest-api/generation/synchronous-generation/generate-single-image Examples showing how to send a POST request to the banner-builder generation endpoint using different programming environments. ```bash curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json" \ -d '{ "template_format_name": "main-crisp", "elements": { "image": { "image_url": "https://mycompany.com/image.jpeg", "fitting_type": "cover", "alignment": "middle center" }, "text_title": { "payload": "Send best wishes to your lovelies with little easter gifts!", "color": "#FFFFFF", "font_size": 48, "font": "61566327-33c5-11ea-9877-92672c1b8195", "font_weight": 700, "line_height": 120, "alignment": "top left" } } }' \ https://api.abyssale.com/banner-builder/{designId}/generate ``` ```javascript const axios = require('axios'); const payload = { "template_format_name": "main-crisp", "elements": { "image": { "image_url": "https://mycompany.com/image.jpeg", "fitting_type": "cover", "alignment": "middle center" }, "text_title": { "payload": "Send best wishes to your lovelies with little easter gifts!", "color": "#FFFFFF", "font_size": 48, "font": "61566327-33c5-11ea-9877-92672c1b8195", "font_weight": 700, "line_height": 120, "alignment": "top left" } } } axios.post("https://api.abyssale.com/banner-builder/{designId}/generate", payload, { headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000} }).then(response => { console.log(response.data) }) ``` ```python import json import requests image_generation_payload = { "template_format_name": "main-crisp", "elements": { "image": { "image_url": "https://mycompany.com/image.jpeg", "fitting_type": "cover", "alignment": "middle center" }, "text_title": { "payload": "Send best wishes to your lovelies with little easter gifts!", "color": "#FFFFFF", "font_size": 48, "font": "61566327-33c5-11ea-9877-92672c1b8195", "font_weight": 700, "line_height": 120, "alignment": "top left" } } } r = requests.post("https://api.abyssale.com/banner-builder/{designId}/generate", headers={"x-api-key": "YOUR-API-KEY", "Content-Type": "application/json"}, data=json.dumps(image_generation_payload), timeout=30 ) r.json() ``` -------------------------------- ### Input Video Customization Example Source: https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-videos Configure input video properties such as muting audio. Ensure the video URL is correctly formatted. ```json "video_element_name": { "video_url": "https://example.com/video.mp4", "audio_muted": 0, } ``` -------------------------------- ### GET /projects Source: https://developers.abyssale.com/rest-api/projects Retrieve a list of all projects associated with the workspace. ```APIDOC ## GET /projects ### Description Retrieve all of your projects (containing id, name & creation date). ### Method GET ### Endpoint /projects ### Response #### Success Response (200) - **id** (string) - Unique identifier of the project - **name** (string) - Name of the project - **created_at_ts** (integer) - Unix timestamp when the project was created #### Response Example [ { "id": "uuid", "name": "Project Name", "created_at_ts": 1625097600 } ] ``` -------------------------------- ### Configure Video Layer Properties Source: https://developers.abyssale.com/rest-api/generation/element-properties/video Example JSON structure for defining a video layer's URL, audio state, and visibility. ```json "video_element_name": { "video_url": "https://example.com/video.mp4", "audio_muted": 0, "hidden": false } ``` -------------------------------- ### Configure Fully Decorated Text Source: https://developers.abyssale.com/rest-api/generation/element-properties/text Examples of fully decorated text payloads using HTML-like tags for styling and various visual properties. ```json "payload": "Lorem i<c=#ff0000><u>p</u></c>su<s>m</s> is simply <c=#1A47FF>dummy</c> <u>text</u>" "color": "#ffffff" "background_color": "#8A4F4F" "background_padding": "2 6" "skew_y": -4 "alignment": "middle center" "font_size": 30 "line_height": 150 "shadow_color": "#000080" "shadow_blur": 3 "shadow_offset_x": 0 "shadow_offset_y": 6 ``` ```json "payload": "Lorem i<c=cmyka(0,100,100,0)><u>p</u></c>su<s>m</s> is simply <c=cmyka(90,72,0,0,100)>dummy</c> <u>text</u>" "color": "cmyka(0,0,0,0,100)" "background_color":"cmyka(0,43,43,46)" "background_padding": "2 6" "skew_y": -4 "alignment": "middle center" "font_size": 30 "line_height": 150 "shadow_color":cmyka(100,100,0,50,100)" "shadow_blur": 3 "shadow_offset_x": 0 "shadow_offset_y": 6 ``` -------------------------------- ### Retrieve Fonts via API Source: https://developers.abyssale.com/rest-api/fonts Examples for fetching the list of fonts using different programming environments. Replace {YOUR-API-KEY} with your actual API key. ```bash curl -H "x-api-key: {YOUR-API-KEY}" -H "Content-Type: application/json" https://api.abyssale.com/fonts ``` ```javascript const axios = require('axios'); axios.get("https://api.abyssale.com/fonts", {headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000}}).then(response => { console.log(response.data) }) ``` ```python import requests r = requests.get("https://api.abyssale.com/fonts", headers={"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json"}, timeout=30) r.json() ``` -------------------------------- ### Request Print Generation Source: https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-pdfs-for-printing Examples of how to trigger an asynchronous print generation request using various programming languages. ```curl curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json" \ -d '{ "template_format_names": [ "postcard", "tabloid-vertical" ], "elements": { "root": { "background_color": "cmyk(0,0,0,0)" }, "text_0": { "payload": "Lorem ipsum", "color": "cmyka(0,0,0,100,100)", "font_size": 24, "font": "6156629c-33c5-11ea-9877-92672c1b8195", "font_weight": 400, "line_height": 130, "alignment": "top left", "hidden": false } } }' \ https://api.abyssale.com/async/banner-builder/{design_id}/generate ``` ```javascript const axios = require('axios'); const payload = { "template_format_names": [ "postcard", "tabloid-vertical" ], "elements": { "root": { "background_color": "cmyk(0,0,0,0)" }, "text_0": { "payload": "Lorem ipsum", "color": "cmyka(0,0,0,100,100)", "font_size": 24, "font": "6156629c-33c5-11ea-9877-92672c1b8195", "font_weight": 400, "line_height": 130, "alignment": "top left", "hidden": false } } } axios.post("https://api.abyssale.com/async/banner-builder/{design_id}/generate", payload, { headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000} }).then(response => { console.log(response.data) }) ``` ```python import json import requests image_generation_payload = { "template_format_names": [ "postcard", "tabloid-vertical" ], "elements": { "root": { "background_color": "cmyk(0,0,0,0)" }, "text_0": { "payload": "Lorem ipsum", "color": "cmyka(0,0,0,100,100)", "font_size": 24, "font": "6156629c-33c5-11ea-9877-92672c1b8195", "font_weight": 400, "line_height": 130, "alignment": "top left", "hidden": false } } } r = requests.post("https://api.abyssale.com/async/banner-builder/{design_id}/generate", headers={"x-api-key": "YOUR-API-KEY", "Content-Type": "application/json"}, data=json.dumps(image_generation_payload), timeout=30 ) r.json() ``` -------------------------------- ### Example Response: List of Designs Source: https://developers.abyssale.com/rest-api/designs This JSON array represents a successful response from the /designs endpoint, listing two static designs with their respective IDs, names, creation/update timestamps, and preview URLs. ```json [ { "id": "3f1900f0-9a0f-4d3f-867e-1bb3a6e4fa2d", "name": "Abyssale demo - FB Square", "type": "static", "created_at": 1681215684, "updated_at": 1681217794, "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/65422510-332e-4da6-ab50-d40ff532d000.png", "category_name": "Abyssale Demo" }, { "id": "46d22c62-d134-44d3-a040-138e4ea9ea08", "name": "Abyssale demo - FB Feed", "type": "static", "created_at": 1688631025, "updated_at": 1688977170, "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/9c872731-da6f-4923-b342-7c4250ac94cc.png", "category_name": "Abyssale Demo" } ] ``` -------------------------------- ### Define Text Color Source: https://developers.abyssale.com/rest-api/generation/element-properties/text Examples of setting text color using hexadecimal, linear gradients, or CMYKA values. ```json "color": "#1A47FF" ``` ```json "color": "linear-gradient(0% 0% 100% 0%,0% #0a68ff 1,100% #ff0000 1)" ``` ```json "color": "cmyka(89,51,0,13,100)" ``` -------------------------------- ### Generate HTML5 Banner Ads Request Source: https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-html5-banner-ads Examples for triggering the asynchronous generation of HTML5 assets via the API. ```bash curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json" \ -d '{ "callback_url": "https://webhook.mycompany.com/images", "image_file_type": "html5", "html5": { "click_tag": "{MY_CLICK_TAG}", "page_title": "{MY_PAGE_TITLE}", "ad_network": "default", "repeat": 0, "include_backup_image": false }, "template_format_names": ["facebook-feed", "instagram-post", "iab-medium"], "elements": { "primary_text": { "payload": "New branding available.", "color": "#FF0000" } } }' \ https://api.abyssale.com/async/banner-builder/{design_id}/generate ``` ```javascript const axios = require('axios'); const payload = { "callback_url": "https://webhook.mycompany.com/images", "image_file_type": "html5", "html5": { "click_tag": "{MY_CLICK_TAG}", "page_title": "{MY_PAGE_TITLE}", "ad_network": "default", "repeat": 0, "include_backup_image": false }, "template_format_names": ["facebook-feed", "instagram-post", "iab-medium"], "elements": { "primary_text": { "payload": "New branding available.", "color": "#FF0000" } } } // Replace {id} by your template ID axios.post("https://api.abyssale.com/async/banner-builder/{design_id}/generate", payload, { headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000} }).then(response => { console.log(response.data) }j ``` ```python import json import requests image_generation_payload = { "callback_url": "https://webhook.mycompany.com/images", "image_file_type": "html5", "html5": { "click_tag": "{MY_CLICK_TAG}", "page_title": "{MY_PAGE_TITLE}", "ad_network": "default", "repeat": 0, "include_backup_image": false }, "template_format_names": ["facebook-feed", "instagram-post", "iab-medium"], "elements": { "primary_text": { "payload": "New branding available.", "color": "#FF0000" } } } ``` -------------------------------- ### Callback URL Setup Source: https://developers.abyssale.com/rest-api/generation/asynchronous-generation Configure how to receive asynchronous generation results. You can use a job-specific callback URL by including `callback_url` in your request, or set up a global webhook endpoint for all asynchronous results. ```APIDOC ## Callback URL Setup There are two distinct methods for receiving asynchronous generation results. Only one method is necessary to receive notifications for any given batch job. ### Option 1: Job-Specific Callback Include the `callback_url` parameter in the JSON body of your asynchronous generation request. Use this if you need a specific, one-time endpoint or want to override your global settings for a particular request. ### Option 2: Global Webhook Endpoint Configure a new webhook endpoint and subscribe to the `NEW_BANNER_BATCH` event via the Abyssale dashboard settings. Use this if you want all asynchronous generation results for your workspace delivered automatically to a single, persistent endpoint. * Abyssale will send complete generation results to this URL (callback_url OR the webhook endpoint) with a `JSON` payload as a `POST` query. ### Notification Mechanism * Automatic notification after asset generation * Includes successful assets and generation errors ### Payload Structure ```json { "generation_request_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "banners": [ { "id": "64238d01-d402-474b-8c2d-fbc957e9d290", "file": { "type": "jpeg", "url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/ee6739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg", "cdn_url": "https://cdn.abyssale.com/demo/ee6739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg", "filename": "ee6739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg" }, "format": { "id": "facebook-post", "width": 1200, "height": 1200 }, "template": { "id": "64238d01-d402-474b-8c2d-fbc957e9d290", "name": "Ad campaign fall 2022", "type": "static", "created_at": 1649942114, "updated_at": 1649942114, "category_name": "Fall campaigns" } } ], "errors": [ { "template_format_name": "string", "reason": "string" } ] } ``` ### Payload Details * `banners`: Successfully generated assets * `errors`: Formats that failed generation * Each successful banner includes file URLs, design details ``` -------------------------------- ### NEW_BANNER_BATCH Event Payload Source: https://developers.abyssale.com/webhooks/events/banner-events Example payload structure for the asynchronous batch generation completion event. ```json { "generation_request_id": "c18c3cec-14c2-4539-99d4-92623b6a4aef", "banners": [ { "id": "ec3a9fcd-f209-4077-b5ea-037d4bdfa9f2", "file": { "type": "jpeg", "url": "url/name.jpeg", "cdn_url": "cdn_url/name.jpeg", "filename": "name.jpeg" }, "format": { "id": "facebook", "width": 1200, "height": 628 }, "template": { "id": "834362df-966b-46fb-a92b-213f3c2ceeac", "name": "Template name", "created_at": 1649682431, "updated_at": 1649682494 } } ], "errors":[ { template_format_name: "(Placeholder Format, will be the real value)", reason: "Element text_placeholder error: The text 'Placeholder text' cannot fit within the defined space.", } ] } ``` -------------------------------- ### NEW_EXPORT Payload Example Source: https://developers.abyssale.com/webhooks/events/global-events Represents the JSON structure returned when an export job completes. ```json { "export_id": "54e62358-2656-455c-afd7-66d5ed3dd581", "archive_url": "url.zip", "requested_at": 1649838051, "generated_at": 1649838135 } ``` -------------------------------- ### Retrieve template details JSON response Source: https://developers.abyssale.com/rest-api/designs/design-details Example of the JSON structure returned when fetching template details. Advanced properties can be accessed by appending ?i=advanced to the request URL. ```json { "template_id": "7dc0229b-cc0e-4fe5-971d-325164480887", "name": "Abyssale demo - FB Feed", "type": "static", "created_at": 1681215684, "updated_at": 1681217794, "category_name": "Abyssale Demo", "formats": [ { "id": "medium-rectangle", "uid": "9b57d65e-eb2c-4a74-a51e-4482917c248a", "width": 300, "height": 250, "preview_url": "https://public-example-link.com/preview/87f7f83b-894f-4900-abe2-3e0e769b12d7.png" }, { "id": "wide-skyscraper", "uid": "088afbb8-bace-4f17-82e4-d30fc6719f4d", "width": 160, "height": 600, "preview_url": "https://public-example-link.com/preview/87f7f83b-894f-4900-abe2-3e0e769b12d7-wide-skyscraper.png" } ], "elements": [ { "name": "root", "type": "container", "settings": { "is_mandatory": false }, "attributes": [ { "id": "background_color", "help": "6 digits hexadecimal background color of the banner (i.e. #F3F3F3)", "values": { "medium-rectangle": "#ffffff", "wide-skyscraper": "#c3bfbf" } } ], "layout": { "medium-rectangle": { "x": 0, "y": 0, "width": 300, "height": 250 }, "wide-skyscraper": { "x": 0, "y": 0, "width": 160, "height": 600 } } }, { "name": "tb-text_0", "type": "text", "settings": { "is_mandatory": false }, "attributes": [ { "id": "payload", "help": "Text content (i.e. Lorem ipsum)", "values": { "medium-rectangle": "Lorem Ipsum", "wide-skyscraper": "Test" } }, { "id": "color", "help": "6 or 8 digits hexadecimal color of the text (i.e. #EAEAEA)", "values": { "medium-rectangle": "#000000", "wide-skyscraper": "#000000", } } ], "layout": { "medium-rectangle": { "x": 20, "y": 40, "width": 200, "height": 50 }, "wide-skyscraper": { "x": 10, "y": 20, "width": 100, "height": 100 } } }, ] } ``` -------------------------------- ### Send Asynchronous GIF Generation Request (Javascript) Source: https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-animated-gifs Initiate an asynchronous GIF generation request using Javascript with the axios library. This example demonstrates setting up the payload with callback URL, image type, GIF parameters, template formats, and element data. ```javascript const axios = require('axios'); const payload = { "callback_url": "https://webhook.mycompany.com/images", "image_file_type": "gif", "gif": { "max_fps": 9, "repeat": -1 }, "template_format_names": ["facebook-feed", "instagram-post", "iab-medium"], "elements": { "primary_text": { "payload": "New branding available.", "color": "#FF0000" } } } // Replace {id} by your template ID axios.post("https://api.abyssale.com/async/banner-builder/{design_id}/generate", payload, { headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000} }).then(response => { console.log(response.data) } ``` -------------------------------- ### GET /fonts Source: https://developers.abyssale.com/rest-api/fonts Retrieve a list of all custom and Google fonts available in your account. ```APIDOC ## GET /fonts ### Description Retrieve all of your fonts (custom & google fonts). ### Method GET ### Endpoint https://api.abyssale.com/fonts ### Response #### Success Response (200) - **id** (string) - Font unique ID, this parameter can be used to force a specific font on a text or a button element. - **name** (string) - The font name. - **available_weights** (array) - The list of weights supported by this font. - **type** (string) - Either `google` for the Google fonts or `custom` for your uploaded fonts. #### Response Example [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Roboto", "available_weights": [400, 700, "400-italic"], "type": "google" } ] ``` -------------------------------- ### Configure basic illustration properties Source: https://developers.abyssale.com/rest-api/generation/element-properties/illustration Sets the illustration file and alignment for an element. ```json "illustration_file": "tropical_fish" "alignment": "middle center" ``` -------------------------------- ### TEMPLATE_STATUS Webhook Payload Source: https://developers.abyssale.com/webhooks/events/design-events Example JSON payload received when a design's workflow status is updated. ```json { "id": "873608a1-e498-47dd-a36d-bd065e3e2b8e", "name": "Template name", "created_at": 1623229458, "updated_at": 1623229457, "status": "APPROVED", "status_updated_at": 1649837939 } ``` -------------------------------- ### POST /projects Source: https://developers.abyssale.com/rest-api/projects Create a new project to organize templates and images. ```APIDOC ## POST /projects ### Description Create a new project to organize your templates and images. ### Method POST ### Endpoint /projects ### Parameters #### Request Body - **name** (string) - Required - Name of the project (2-100 characters) ### Request Example { "name": "New Project" } ### Response #### Success Response (200) - **id** (string) - Unique identifier of the project - **name** (string) - Name of the project - **created_at_ts** (integer) - Unix timestamp when the project was created #### Response Example { "id": "uuid", "name": "New Project", "created_at_ts": 1625097600 } ``` -------------------------------- ### Initiate Asynchronous Image Generation (Python) Source: https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-images This Python script shows how to make an asynchronous image generation request using the `requests` library. Substitute `{YOUR-API-KEY}` and `{design_id}` with your actual values. The `callback_url` is required for receiving asynchronous notifications. ```python import json import requests image_generation_payload = { "callback_url": "https://webhook.mycompany.com/images", "template_format_names": ["facebook-feed", "instagram-post", "iab-medium"], "elements": { "primary_text": { "payload": "New branding available.", "color": "#FF0000" } } } # Do not forget to replace {YOUR-API-KEY} and {template_id} r = requests.post("https://api.abyssale.com/async/banner-builder/{design_id}/generate", headers={"x-api-key": "YOUR-API-KEY", "Content-Type": "application/json"}, data=json.dumps(image_generation_payload), timeout=30 ) r.json() ``` -------------------------------- ### Initiate Asynchronous Image Generation (cURL) Source: https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-images Use this cURL command to send a POST request to the asynchronous banner builder endpoint. Ensure you replace `{YOUR-API-KEY}` and `{design_id}` with your actual credentials and design ID. The `callback_url` is essential for receiving generation status updates. ```bash curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json" \ -d '{ "callback_url": "https://webhook.mycompany.com/images", "template_format_names": ["facebook-feed", "instagram-post", "iab-medium"], "elements": { "primary_text": { "payload": "New branding available.", "color": "#FF0000" } } }' \ https://api.abyssale.com/async/banner-builder/{design_id}/generate ``` -------------------------------- ### OpenAPI Specification for Fonts Source: https://developers.abyssale.com/rest-api/fonts The OpenAPI definition for the /fonts endpoint, detailing the Font schema and GET request structure. ```json {"openapi":"3.0.3","info":{"title":"API Reference - Abyssale","version":"0.0.1"},"tags":[{"name":"Fonts"}],"servers":[{"url":"https://api.abyssale.com","description":"Main Production Server"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"description":"All of your Abyssale requests must contain a `x-api-key header` with your API Key.","type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"Font":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Font unique ID, this parameter can be used to force a specific font on a text or a button element."},"name":{"type":"string","description":"The font name"},"available_weights":{"type":"array","items":{"oneOf":[{"type":"number","enum":[100,200,300,400,500,600,700,800,900]},{"type":"string","enum":["100-italic","200-italic","300-italic","400-italic","500-italic","600-italic","700-italic","800-italic","900-italic"]}],"description":"The list of weights supported by this font"}},"type":{"type":"string","enum":["google","custom"],"description":"Either `google` for the Google fonts or `custom` for your uploaded fonts."}},"required":["id","name","available_weights","type"]}}},"paths":{"/fonts":{"get":{"tags":["Fonts"],"summary":"Get fonts","description":"Retrieve all of your fonts (custom & google fonts)","responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Font"}}}}}}}}}} ``` -------------------------------- ### Configure Text-to-Image Prompt Source: https://developers.abyssale.com/rest-api/generation/element-properties/image Define a text-to-image prompt for asynchronous generation. This property is ignored if image_url or image_encoded is provided. ```json "text_to_image": "A sleek, modern glass villa situated in the middle of a minimalist lavender field. Sharp lines, reflection of the blue sky in the windows, wide-angle shot, architectural photography style, hyper-realistic." ``` -------------------------------- ### Image Overlay Configuration Source: https://developers.abyssale.com/rest-api/generation/element-properties/image Configuration parameters for applying gradient overlays to images. ```APIDOC ## Image Overlay Configuration ### Description Configure gradient overlays on images using direction and color parameters. ### Parameters #### Request Body - **overlay_direction** (String) - Required - Direction of the gradient (e.g., "horizontal", "vertical", "diagonal"). - **overlay_color_1** (String) - Required - Starting color in alpha hexadecimal format (e.g., "#FF000080"). - **overlay_color_2** (String) - Required - Ending color in alpha hexadecimal format (e.g., "#0000FF1A"). ### Request Example { "overlay_direction": "horizontal", "overlay_color_1": "#FF000080", "overlay_color_2": "#0000FF1A" } ``` -------------------------------- ### GET /designs/{designId} Source: https://developers.abyssale.com/rest-api/designs/design-details Retrieve the details of a specific design, including its general information, supported formats, elements, and their customizable properties. ```APIDOC ## GET /designs/{designId} ### Description Retrieve the details of a design (general information, formats, elements & properties). ### Method GET ### Endpoint /designs/{designId} ### Parameters #### Path Parameters - **designId** (string) - Required - Unique identifier (UUID) of the design. ### Responses #### Success Response (200) - **id** (string) - Unique identifier (UUID) of the design. - **name** (string) - Name of the design. - **type** (string) - Type of the design (static, animated, printer, printer_multipage). - **created_at** (integer) - Timestamp of when the design has been created. - **updated_at** (integer) - Timestamp of when the design has been updated for the last time. - **category_name** (string) - Design Category. - **formats** (array) - The list of formats available in the design. Each format object contains: - **id** (string) - Unique identifier (name) of the format. - **uid** (string) - Unique UUID of the format. - **width** (number) - Width of the format. - **height** (number) - Height of the format. - **preview_url** (string) - Preview Image URL of the format. - **dynamic_image_url** (string) - URL of the existing dynamic image for this format. - **elements** (array) - The list of all elements (& customizable properties) contained in the design. Each element object contains: - **name** (string) - Layer name (`root` is a special element that allows to customize the image background color.). - **type** (string) - Layer type (container, text, button, image, logo, shape, illustration, rating, qrcode, chart). - **attributes** (array) - List of all attributes. Each attribute object contains: - **id** (string) - The attribute name. - **help** (string) - An helper to understand what is this attribute. - **values** (object) - The value of the attribute related to a format. - **variables** (object) - Variables used within the text layers of the design. Keys represent variable names (without braces), and values represent the placeholder format in the design (e.g. "{name}"). #### Response Example ```json { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Example Design", "type": "static", "created_at": 1678886400, "updated_at": 1678886400, "category_name": "Social Media", "formats": [ { "id": "facebook_feed", "uid": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "width": 1200, "height": 628, "preview_url": "https://example.com/previews/facebook_feed.png", "dynamic_image_url": "https://api.abyssale.com/images/abcdef1234567890" } ], "elements": [ { "name": "root", "type": "container", "attributes": [ { "id": "background_color", "help": "Background color of the design.", "values": { "facebook_feed": "#FFFFFF" } } ] }, { "name": "Title Text", "type": "text", "attributes": [ { "id": "text_content", "help": "The text content.", "values": { "facebook_feed": "Hello, Abyssale!" } }, { "id": "font_size", "help": "Font size in pixels.", "values": { "facebook_feed": "48" } } ] } ], "variables": { "name": "{name}" } } ``` #### Error Response (404) - **message** (string) - Design Not found ``` -------------------------------- ### GET /designs Source: https://developers.abyssale.com/rest-api/designs Retrieve all of your designs, including their ID, name, creation date, and update date. You can filter designs by category or type. ```APIDOC ## GET /designs ### Description Retrieve all of your designs (containing for each the id, name, creation date & update date) ### Method GET ### Endpoint /designs ### Parameters #### Query Parameters - **category_id** (string) - Optional - Unique identifier (UUID) of a category. Filter designs by a category. - **type** (string) - Optional - Filter designs by one of these types: static, animated, printer, printer_multipage ### Responses #### Success Response (200) - **id** (string) - Unique identifier (UUID) of the design. - **name** (string) - Name of the design. - **type** (string) - Type of the design (static, animated, printer, printer_multipage). - **created_at** (integer) - Timestamp of when the design has been created. - **updated_at** (integer) - Timestamp of when the design has been updated for the last time. - **preview_url** (string) - Preview Image URL of the first design format. #### Response Example ```json [ { "id": "3f1900f0-9a0f-4d3f-867e-1bb3a6e4fa2d", "name": "Abyssale demo - FB Square", "type": "static", "created_at": 1681215684, "updated_at": 1681217794, "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/65422510-332e-4da6-ab50-d40ff532d000.png", "category_name": "Abyssale Demo" } ] ``` ``` -------------------------------- ### Initiate Asynchronous Image Generation (JavaScript) Source: https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-images This JavaScript code snippet demonstrates how to initiate an asynchronous image generation request using the `axios` library. Remember to replace `{YOUR-API-KEY}` and `{designId}`. The `callback_url` parameter is crucial for asynchronous notifications. ```javascript const axios = require('axios'); const payload = { "callback_url": "https://webhook.mycompany.com/images", "template_format_names": ["facebook-feed", "instagram-post", "iab-medium"], "elements": { "primary_text": { "payload": "New branding available.", "color": "#FF0000" } } } // Replace {id} by your template ID axios.post("https://api.abyssale.com/async/banner-builder/{designId}/generate", payload, { headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000} }).then(response => { console.log(response.data) }) ``` -------------------------------- ### Test API Authentication Source: https://developers.abyssale.com/rest-api/authentication Verify API connectivity by calling the /ready endpoint with the required x-api-key header. ```bash curl -i -H "x-api-key: {YOUR-API-KEY}" https://api.abyssale.com/ready # HTTP/2 200 ``` ```javascript const axios = require('axios'); axios.get("https://api.abyssale.com/ready", {headers: {"x-api-key": "{YOUR-API-KEY}"}}).then(response => { console.log(response.status) // 200 }) ``` ```python import requests r = requests.get("https://api.abyssale.com/ready", headers={"x-api-key": "{YOUR-API-KEY}"}, timeout=30) r.status_code # 200 ``` -------------------------------- ### Get Duplication Request Status Source: https://developers.abyssale.com/rest-api/workspace-templates Poll the status of a template duplication request. Use this endpoint to track the progress of an asynchronous duplication operation. ```APIDOC ## GET /design-duplication-requests/{duplicateRequestId} ### Description Poll the status of a template duplication request. Use this endpoint to track the progress of an asynchronous duplication operation. ### Method GET ### Endpoint /design-duplication-requests/{duplicateRequestId} ### Parameters #### Path Parameters - **duplicateRequestId** (string) - Required - Unique identifier (UUID) of the duplication request ### Response #### Success Response (200) - **request_id** (string) - Unique identifier of the duplication request - **status** (string) - Current status of the duplication request (enum: INIT, IN_PROGRESS, ERROR, COMPLETED) - **created_at_ts** (integer) - Unix timestamp when the duplication request was created - **completed_at_ts** (integer) - Unix timestamp when the duplication was completed (null if not completed) - **errored_at_ts** (integer) - Unix timestamp when the duplication failed (null if not failed) - **target_project** (object) - Information about the target project - **id** (string) - Unique identifier of the project - **name** (string) - Name of the project - **created_at_ts** (integer) - Unix timestamp when the project was created - **designs** (array) - List of duplicated designs (empty if not completed) - **original_design_id** (string) - ID of the original workspace template - **target_design_id** (string) - ID of the newly created template in your project - **target_design_name** (string) - Name of the duplicated template #### Error Response (404) Duplication request not found ``` -------------------------------- ### Configure illustration with primary color Source: https://developers.abyssale.com/rest-api/generation/element-properties/illustration Applies opacity and a primary color using hexadecimal format within the illustration_properties object. ```json "opacity": 68, "illustration_file": "happy_2021", "illustration_properties": { "primary_color": "#FF0000" } ```