Get generated file

GET/banners/{bannerId}

Sample request

cURL

curl -X GET "https://api.abyssale.com/banners/$BANNER_ID" \
  -H "x-api-key: $ABYSSALE_API_KEY"

Node.js

import abyssale from '@abyssale/sdk';

const bannerId = 'YOUR_BANNER_ID';

const { data, error } = await abyssale.getFile(bannerId);

if (error) console.error(error.id, error.message);
else console.log(data);

Python

from abyssale import Abyssale

banner_id = "YOUR_BANNER_ID"

with Abyssale() as client:
    result = client.get_file(banner_id)

print(result)

Example 200 response

{
  "id": "64238d01-d402-474b-8c2d-fbc957e9d290",
  "version": 1,
  "sharing_id": "5fcec999-2bfb-4dd7-ba38-2d9e16c49149",
  "file": {
    "type": "jpeg",
    "url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
    "cdn_url": "https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
    "filename": "996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
    "fallback_image_url": "string"
  },
  "format": {
    "id": "facebook-post",
    "unit": "px",
    "width": 1200,
    "height": 1200
  },
  "template": {
    "id": "64238d01-d402-474b-8c2d-fbc957e9d290",
    "name": "Ad campaign fall 2025",
    "created_at": 1649942114,
    "updated_at": 1649942114
  },
  "project": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "created_at_ts": 0
  },
  "image": {
    "type": "string",
    "url": "string"
  },
  "edit_url": "string",
  "view_url": "string",
  "visual_status": {
    "status": "string",
    "status_updated_at_ts": 0,
    "reason": "string",
    "content_to_replace": "string",
    "content_to_hide": "string"
  }
}

Example 401 error response

{
  "message": "Unauthorized: missing or invalid API key.",
  "id": "unauthorized"
}

Retrieve the metadata and download URLs for a previously generated file (image, video, GIF, HTML5 banner, or PDF). Returns both the S3 storage URL and a CDN-hosted URL suitable for embedding directly in websites or emails.

Path parameters

bannerId string (uuid) required

Unique identifier (UUID) of the file

Response 200

The file's metadata and download URLs.

id string (uuid) always

version integer

Version number of the generated file — an integer counter, NOT the API version. A banner response reports this counter; the vYYYY-MM-DD stamp other responses carry never appears here.

sharing_id string (uuid)

Identifier used for sharing this generated file.

file File always

Show child attributes

type string always

File type. webp and avif are returned when image_file_type asked for them; an html5 generation is delivered as zip. One of "jpeg", "png", "webp", "avif", "pdf", "gif", "mp4", "zip".

url string always

URL of the banner (useful to download the image).

cdn_url string

The CDN URL of the banner (useful to host the image; on a website for instance). (A bandwidth usage limit applies, related to your plan). (Not available for zip)

filename string

Name of the file. If the related design contains a custom naming scheme, the custom name will be available from this property.

fallback_image_url string

Backup JPEG URL — present only when type is zip (HTML5 output).

format Format

Show child attributes

id string

Identifier/name of the format. Absent on multi-page print visuals.

unit string

Unit of width/height — px, or mm/in on print designs.

width number always

Width of the format, in unit. A float on print designs (mm/in).

height number always

Height of the format, in unit. A float on print designs (mm/in).

template DesignSummary

The design this file was generated from.

More about template

A short reference to a design, nested inside another resource. Deliberately narrower than Design — only the fields the parent resource carries.

Show child attributes

id string (uuid) always

Unique identifier (UUID) of the design.

name string always

Name of the design.

created_at integer

updated_at integer

project object

The design's project — present when the design has one.

Show child attributes

id string (uuid)

name string

created_at_ts integer

image object

Deprecated. Deprecated — same information as file.type / file.url.

Show child attributes

type string

url string (uri)

edit_url string

Platform edit URL — only for visuals bookmarked or downloaded in the platform.

view_url string

Platform view URL — only for visuals bookmarked or downloaded in the platform.

visual_status object

Present when the visual carries a review status.

Show child attributes

status string

status_updated_at_ts integer

reason string

content_to_replace string

Review feedback — content the reviewer asked to be replaced.

content_to_hide string

Review feedback — content the reviewer asked to be hidden.

Errors

Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.

Status	When
401	Unauthorized — missing or invalid API key.
404	Banner not found (visual_not_found).
429	Too Many Requests.
500	Internal Server Error — an unexpected error occurred on our side.

Related

• Files guide