Poll async generation request status
Sample request
curl -X GET "https://api.abyssale.com/generation-request/$GENERATION_REQUEST_ID" \
-H "x-api-key: $ABYSSALE_API_KEY"import abyssale from '@abyssale/sdk';
const generationRequestId = 'YOUR_GENERATION_REQUEST_ID';
const { data, error } = await abyssale.getGenerationRequest(generationRequestId);
if (error) console.error(error.id, error.message);
else console.log(data);from abyssale import Abyssale
generation_request_id = "YOUR_GENERATION_REQUEST_ID"
with Abyssale() as client:
result = client.get_generation_request(generation_request_id)
print(result)Example 200 response
{
"id": "00000000-0000-0000-0000-000000000000",
"is_finalized": false,
"banners": [
{
"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"
}
}
],
"errors": [
{
"template_format_name": "string",
"reason": "string"
}
],
"version": "v2026-08-21"
}Example 202 response
{
"id": "00000000-0000-0000-0000-000000000000",
"is_finalized": false,
"banners": [
{
"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"
}
}
],
"errors": [
{
"template_format_name": "string",
"reason": "string"
}
],
"version": "v2026-08-21"
}Example 401 error response
{
"message": "Unauthorized: missing or invalid API key.",
"id": "unauthorized"
}Poll the status of an asynchronous generation request. Use this endpoint to track the progress of a batch generation operation started with the async generate endpoint. The result is available for 7 days after generation.
Path parameters
generationRequestId string (uuid) required
Unique identifier (UUID) of the generation request
Response 200
Generation finished — is_finalized is true and banners is populated.
id string (uuid) always
Unique identifier of the generation request
is_finalized boolean always
Whether the generation is complete. false when the request returns 202, true when it returns 200.
banners array of Banner always
List of generated files (populated once finalized)
Show child attributes
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 array of object
Per-format errors, if any occurred during generation
Show child attributes
template_format_name string
The format name that failed to generate
reason string
The error reason
version string
The API version that produced this response, named by release date (vYYYY-MM-DD). Pattern ^v\d{4}-\d{2}-\d{2}$.
More about version
The API version that produced this response, named by release date (vYYYY-MM-DD). Stamped as a top-level field on JSON object bodies, success and error alike, so a client can always tell which contract answered. There is no version-selection parameter — a single version is maintained at a time.
Two kinds of body are not stamped. Array bodies (the listings) carry no envelope. And a body that already has a version key of its own is left alone — which in practice means Banner, whose version is the generated file's integer counter. So GET /banners/{bannerId} and the synchronous generate are the two responses that do not tell you which contract answered.
The value changes when a new version is released. Match the vYYYY-MM-DD shape rather than pinning today's literal, or your client breaks on the next release.
Response 202
Generation still in progress
id string (uuid) always
Unique identifier of the generation request
is_finalized boolean always
Whether the generation is complete. false when the request returns 202, true when it returns 200.
banners array of Banner always
List of generated files (populated once finalized)
Show child attributes
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 array of object
Per-format errors, if any occurred during generation
Show child attributes
template_format_name string
The format name that failed to generate
reason string
The error reason
version string
The API version that produced this response, named by release date (vYYYY-MM-DD). Pattern ^v\d{4}-\d{2}-\d{2}$.
More about version
The API version that produced this response, named by release date (vYYYY-MM-DD). Stamped as a top-level field on JSON object bodies, success and error alike, so a client can always tell which contract answered. There is no version-selection parameter — a single version is maintained at a time.
Two kinds of body are not stamped. Array bodies (the listings) carry no envelope. And a body that already has a version key of its own is left alone — which in practice means Banner, whose version is the generated file's integer counter. So GET /banners/{bannerId} and the synchronous generate are the two responses that do not tell you which contract answered.
The value changes when a new version is released. Match the vYYYY-MM-DD shape rather than pinning today's literal, or your client breaks on the next release.
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 | Generation request not found (generation_request_not_found). |
410 | Gone — the generation request expired (generation_request_gone; requests are kept 7 days). |
429 | Too Many Requests. |
500 | Internal Server Error — an unexpected error occurred on our side. |