Generations API Reference

Complete documentation for the ModelStack Generations API — create, list, and manage AI-generated images and videos.

Overview

The Generations API provides a unified interface for AI image and video generation across multiple providers. All requests require authentication with an API key.

Base URL

https://api.modelstack.cc

Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_YOUR_API_KEY

Rate Limits

60 requests per minute (per user)
10 concurrent generations (per user)
100 burst requests per minute

POST

Create Generation

/v1/generations

Create a new image or video generation. Returns immediately with a pending generation — poll the generation ID to get the result.

Request Body

Field	Type	Required	Description
type	string	Yes	Generation type, e.g. TEXT_TO_IMAGE, TEXT_TO_VIDEO, IMAGE_TO_IMAGE
prompt	string	Yes	Text prompt describing the desired output
model	string	Yes	Model identifier, e.g. google/nano-banana-2-lite
modelSettings	object	No	Model-specific parameters (aspect ratio, resolution, duration, etc.)

curl -X POST "https://api.modelstack.cc/v1/generations" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TEXT_TO_IMAGE",
    "prompt": "A serene mountain landscape at sunset",
    "model": "google/nano-banana-2-lite",
    "modelSettings": {
      "aspect_ratio": "16:9"
    }
  }'

Response

{
  "id": "gen_abc123",
  "status": "pending"
}

The generation id is used to poll for completion.

GET

Get Generation

/v1/generations/{id}

Get the status and result of a specific generation. Poll this endpoint to check when generation is complete.

curl "https://api.modelstack.cc/v1/generations/gen_abc123" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Response

{
  "id": "gen_abc123",
  "status": "completed",
  "creditsUsed": 40,
  "output": {
    "url": "https://cdn.modelstack.cc/outputs/gen_abc123.png",
    "type": "image/png"
  }
}

GET

List Generations

/v1/generations

List all generations with pagination and optional status filtering.

Query Parameters

Parameter	Type	Default	Description
limit	number	No	Max records (max 100)(default: 25)
offset	number	No	Pagination offset(default: 0)
status	string	No	Filter: pending \| processing \| completed \| failed

curl "https://api.modelstack.cc/v1/generations?limit=10&status=completed" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

DELETE

Delete Generation

/v1/generations/{id}

Delete a completed or failed generation to free up storage.

curl -X DELETE "https://api.modelstack.cc/v1/generations/gen_abc123" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Response

{ "success": true }

Error Handling

The API returns standard HTTP status codes and a consistent error format:

Code	Meaning
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid API key
402	Insufficient Credits — top up your balance
404	Not Found — generation ID doesn't exist
429	Too Many Requests — rate limit exceeded
5xx	Server Error — try again later

{
  "error": {
    "type": "insufficient_credits",
    "message": "Your account does not have enough credits to complete this request.",
    "code": 402
  }
}