Generation Endpoints

Download Videos as Zip

Endpoint:
POST /api/v1/generations/download

Download the generated MP4 videos for a list of generation IDs as a single zip archive in one request. This is the batch counterpart to Get Generated Video — instead of fetching one video at a time, you pass many IDs and receive one .zip.


Authentication

All requests require an API key.
Include your API key in the Authorization header as a Bearer token:

HTTP
Authorization: Bearer YOUR_API_KEY

Request Body

Send a JSON object with a videoIds array of generation IDs.

JavaScript
{
  "videoIds": [4983, 4982, 4981]
}
  • videoIds (number[], required): The IDs of the generations whose videos you want to download. These are the id values returned by the Bulk Generations endpoint. Duplicate IDs are de-duplicated automatically.

Query String Variant

The same archive can be requested with a GET so it can be fetched from a plain link:

HTTP
GET /api/v1/generations/download?ids=4983,4982,4981

Response

  • 200 OK: Returns a application/zip archive (streamed) containing one MP4 per ready generation.
  • 400 Bad Request: The request body or ids parameter is missing or invalid.
  • 404 Not Found: None of the requested IDs map to a downloadable video that you own.

Response Headers

HeaderDescription
Content-Typeapplication/zip
Content-Dispositionattachment; filename="generations-<timestamp>.zip"
X-Skipped-Not-ReadyComma-separated IDs that exist but whose video has not finished yet.
X-Skipped-Not-FoundComma-separated IDs that do not exist or are not owned by your account.

File Names Inside the Archive

Each video is named from its externalId:

  • If an externalId was set on the generation, it is used as the file name (sanitized — any character outside a-z, A-Z, 0-9, -, _ is replaced with _). Example: externalId: "mug-2" → mug-2.mp4.
  • If no externalId was set, the file is named generation-<id>.mp4.
  • If two files would resolve to the same name, the generation ID is appended to keep names unique, e.g. mug-2-4982.mp4.

Credits

Downloading videos does not consume credits. Credits are only spent when generating videos.


Example Usage

cURL

Shell
curl -X POST "https://rotateproduct.com/api/v1/generations/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "videoIds": [4983, 4982, 4981] }' \
  -D - \
  --output generations.zip

The -D - flag prints the response headers to your terminal so you can inspect X-Skipped-Not-Ready / X-Skipped-Not-Found.

JavaScript (fetch)

JavaScript
const response = await fetch(
  'https://rotateproduct.com/api/v1/generations/download',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ videoIds: [4983, 4982, 4981] }),
  },
)

const skippedNotReady = response.headers.get('X-Skipped-Not-Ready')
const skippedNotFound = response.headers.get('X-Skipped-Not-Found')

const blob = await response.blob()
// Save `blob` to disk, e.g. with the File System Access API or a download link.

Error Responses

Validation Error

JavaScript
{
  "success": false,
  "error": {
    "code": 4001,
    "message": "Validation failed",
    "meta": {
        "friendlyMessage": "Maximum 100 videoIds are allowed",
        "type": "error",
        "title": "Validation Error"
    }
  }
}

Nothing to Download

JavaScript
{
  "success": false,
  "error": {
    "code": 4006,
    "message": "downloadable generations not found",
    "meta": {
        "friendlyMessage": "downloadable generations not found",
        "type": "error",
        "title": "Resource Not Found",
        "resource": "downloadable generations"
    }
  }
}

Best Practices

  • Wait until generations have a succeeded status before requesting the archive — see Get Generation Status. IDs that are not ready are skipped.
  • Always inspect the X-Skipped-* headers so you know which IDs to retry later.
  • Keep batches reasonable. The archive is streamed, but very large batches take longer to assemble. The hard limit is 100 IDs per request.
  • Download promptly. Videos are only retained for 1 hour after creation.

FAQ

Q: What happens if some videos are still processing?
A: They are skipped and listed in the X-Skipped-Not-Ready response header. The archive still contains every video that was ready. Retry those IDs once they reach a succeeded status.

Q: Can I download videos that belong to another account?
A: No. Only generations owned by the API key making the request are included; any others are reported in X-Skipped-Not-Found.

Q: Does this cost credits?
A: No. Downloading is free — credits are only used when generating videos.


For more help, contact info@rotateproduct.com.