Genspicy API
Generate images and videos from Genspicy templates. Build your workflow with a simple REST API.
Get your API key →Start building
- Get an API key. Recharge at least $100 in API credits, generate your key, then pass it in the
X-API-Keyheader on every request. - Choose a template. List templates to find its
id, credit cost and the inputs it needs. - Make a generation. Upload any input files, create a generation, then poll Get a generation for the result.
Base URL
https://openapi.genspicy.ai/openapi/v1Requests and responses use JSON. Successful responses return code: 0, message and data. Failed requests return a non-zero error code and a message.
Explore the API
Authentication
Authenticate every public API request with your API key.
Send your key in the X-API-Key header. Requests without a valid key return 401.
Get a key
Log in to Genspicy, recharge at least $100 in API credits, then generate your key from API keys. Select Reveal to view the full key or Copy to save it securely on your server.
Keep it on your server
Store the key in an environment variable. The JavaScript and Python examples read GENSPICY_API_KEY from your environment.
Generation workflow
Submit a job, then retrieve the result when processing finishes.
- Pick a template. List templates returns each template's
id,costand what it needs:prompt_required,duration_required,input_mediasand optionalfeatures. - Upload inputs. For each item in
input_medias, create an upload URL, PUT the file and keep thefile_url. Pass the files in the order and with the types specified by the template. Skip this step wheninput_mediasis empty. - Create the generation. Call Create a generation. Credits are charged when the request is accepted, and the response contains the generation
id. - Poll for the result. Call Get a generation about every 10 seconds until
statusissucceededorfailed. Download successful results fromcontent_url.
API keys
Manage access for your server-side integrations.
API access
API account
Loading your API account…
Recharge credits
API access requires a first recharge of $100 or more. Recharges are paid with crypto. Recharges of $1,000 or more get 30% extra credits.
Recharge
Loading recharge options…
1 API credit = $0.01. API credits are separate from your Genspicy website diamonds and can only be used through the API.
Get account
/accountReturns the account bound to your API key and its credit balance. Use it to verify the key works and to check how many credits are left.
Response fields
account_id
uuid
Account bound to the API key.
credits
integer
Available API credits ($0.01 each). The value is at least zero. These credits are separate from your website diamonds.
status
string
active indicates a usable account, and restricted indicates a restricted account.
List templates
/templatesReturns a paginated list of published templates. Use keyword to filter by template name.
Query parameters
keyword
string
Optional
Case-insensitive keyword search on the template name.
page
integer
Optional
Page number, starting at 1. Default 1.
page_size
integer
Optional
Items per page, 1–100. Default 20.
Response fields
data.items[] — each template and everything you need to generate with it. Pagination is in data.total, data.page and data.page_size.
id
uuid
Template id. Send it as generation_template_id. Names are not unique — store the id.
name
string
Template name.
output_type
string
image or video.
thumbnail_url
uri
Cover image for showing the template on your site.
preview_video_url
uri
Short preview video of the template.
updated_at
date-time
Last time the template changed. Compare it with your stored copy to pick up new or changed templates.
cost
integer
Base credits for one generation. Templates with a selectable duration show the five-second price.
duration
integer
Default output duration in seconds, from 5 to 12. Omitted when not applicable.
prompt_required
boolean
If true, prompt is required when generating.
duration_required
boolean
If true, duration is required; otherwise omit it.
supports_extend_video
boolean
If true, extend_video may be sent. Extension needs exactly one input video.
extend_cost
integer
Additional credits when extend_video is used. Omitted when unsupported.
input_medias
object[]
Media you must supply. Empty when none is needed (for example text-to-image).
type
string
image or video.
description
string
What the input should be.
features
object[]
Optional add-ons. Only these names are accepted in selected_features.
name
string
Feature name to send.
cost
integer
Additional credits when selected.
Create an upload URL
/uploadsReturns a presigned upload URL. Send the file with PUT and the returned headers, then pass file_url as input_medias[].url when you create a generation. If a file with the same extension and SHA-256 is already stored, the response contains only file_url.
Body parameters
file_name
string
Required
Original file name with a supported extension: .jpg, .jpeg, .png, .webp, .mp4, .mov or .webm.
content_type
string
Required
image/jpeg, image/png, image/webp, video/mp4, video/quicktime or video/webm.
hash
string
Required
SHA-256 digest of the file bytes as 64 hexadecimal characters.
Limits
Generation validates image content, file size and dimensions. Images must be 300–6000 pixels wide, contain no more than 25 million pixels, have an aspect ratio of 0.4–2.5 and be no larger than 7 MB.
Response fields
file_url
uri
Use it as input_medias[].url.
upload_url
uri
Presigned PUT URL. Absent when the file already exists.
headers
object
Headers to send with the PUT request. Absent when the file already exists.
expires_at
date-time
When upload_url expires. Upload URLs are valid for 15 minutes by default.
Create a generation
/generationsStarts an image or video generation. The template decides the output type. Credits are charged when the request is accepted and refunded automatically if the generation fails. Requests rejected with a 4xx status are not charged.
Up to 10 generations can be processing at the same time. More return 429 — see Rate limits.
Pricing
Templates with selectable video durations charge 20 credits per second from 5 to 12 seconds. Refer to the template for other base prices and any additional charges for selected_features or video extension.
Body parameters
generation_template_id
uuid
Required
Template id from List templates.
prompt
string
Optional
Required when the template has prompt_required: true.
duration
integer
Optional
A whole number from 5 to 12 seconds. Send it only when the template has duration_required: true.
input_medias
object[]
Optional
Match the number, order and types of the template's input_medias. Omit when that list is empty.
type
string
Required
image or video.
url
uri
Required
Use the file_url returned by Create an upload URL.
selected_features
string[]
Optional
Add-on names from the template's features. Each adds its own cost.
extend_video
boolean
Optional
Send true only when the template has supports_extend_video: true.
Response fields
id
uuid
Generation id. Store it to poll for the result.
status
string
processing.
cost
integer
Total credits charged, including the selected features and video extension when used.
Get a generation
/generations/{id}Returns the status and result of one generation. Poll it until status is succeeded or failed. Generations that do not belong to your account return 404.
Path parameters
id
uuid
Required
Generation id returned by Create a generation.
Response fields
id
uuid
Generation id.
status
string
processing, succeeded or failed. See Generation statuses.
generation_template_id
uuid
Template used for this generation.
output_type
string
image or video.
created_at
date-time
When the generation was submitted.
cost
integer
Total credits charged for this generation. Refunded automatically if it fails.
content_url
uri
Output file URL, present only when the generation succeeds.
reason
string
Present only when the status is failed. The current reason is generation_failed.
List generations
/generationsReturns your generations, newest first. Use it for reconciliation or to recover results you missed while polling. To total your spending for a period, filter by created_after and created_before and add up cost for items that did not fail.
Query parameters
page
integer
Optional
Page number, starting at 1. Default 1.
page_size
integer
Optional
Items per page, 1–100. Default 20.
status
string
Optional
Filter by processing, succeeded or failed.
created_after
date-time
Optional
Only generations submitted at or after this time, as an RFC 3339 timestamp, for example 2026-11-01T00:00:00Z.
created_before
date-time
Optional
Only generations submitted at or before this time, for example 2026-11-30T23:59:59Z.
Response fields
data.items[] has the same fields as Get a generation, plus data.total, data.page and data.page_size.
Generation statuses
Track a generation from submission to its final result.
| Status | Meaning |
|---|---|
| processing | Generating. Keep polling. |
| succeeded | Done. content_url points to the output. |
| failed | Generation failed and the credits were refunded. reason is generation_failed. |
Poll Get a generation about every 10 seconds while the status is processing.
Rate limits
Keep requests within these limits to avoid interruptions.
| Scope | Limit |
|---|---|
| Generations processing at the same time | 10 per account |
A Create a generation request over this limit returns 429 with code 10042 and no charge. Wait for a running generation to finish, then retry. The response omits Retry-After.
Errors
Use the HTTP status and the code in the response to understand a failed request. Don't build logic on message.
| HTTP | code | Meaning |
|---|---|---|
| 400 | 10001 | Invalid request body, unavailable feature, invalid duration or invalid time range. |
| 400 | 10018 10019 10021 | Upload request: file_name doesn't match content_type, the type isn't supported, or hash isn't a SHA-256 hex string. |
| 400 | 10023 10030 | generation_template_id or the generation id is missing or not a valid UUID. |
| 400 | 10024 10032 | page, page_size or status is out of range. |
| 400 | 10035 | The template requires a prompt. |
| 401 | 10022 | Missing, invalid, expired or revoked API key. |
| 403 | 10034 | The account is missing, deleted or unavailable. |
| 404 | 10025 | Template not found or no longer available. |
| 404 | 10031 | Generation not found in your account. |
| 422 | 10033 | Not enough credits. Recharge and retry. |
| 422 | 10038 | An input file is invalid, missing, has the wrong type or did not pass content checks. See the upload requirements. |
| 422 | 10049 | The template doesn't support extend_video. |
| 429 | 10042 | 10 generations are already processing. See Rate limits. |
| 500 | 10000 | Unexpected server error. Retry later. |
| 503 | 10000 | A required service is temporarily unavailable. Retry later. |
Requests rejected with a 4xx error are not charged. A generation that is accepted but fails later is reported on the generation itself — see Generation statuses.