Bulk Generations

Endpoint:
POST /api/v1/generations

Use this endpoint to generate multiple 3D rotating product videos in a single request. Each generation consumes 5 credits from your account.

Authentication

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

Authorization: Bearer YOUR_API_KEY

Request Body

Send a JSON object with a generations array.

Each item must include:

• externalId (string, optional): A unique identifier for tracking within your systems (recommended). It is echoed back as external_id on each item in the response.
• imageUrl (string): The URL (or DataUrl data:image/jpeg;base64,/9j/...) of the product image. This is used as the first frame of the video.
• endImageUrl (string, optional): The URL (or DataUrl) of an image to use as the final frame of the video. When provided, the generation interpolates from imageUrl (first frame) to endImageUrl (last frame). If this image fails to process, the generation is rejected and appears in failedGenerations.
• description (string, optional): A short description of the product. (Optional but recommended for better results.)

{
  "generations": [
    {
      "imageUrl": "https://example.com/image1.jpg",
      "description": "red running shoe",
      "externalId": "shoe-1"
    },
    {
      "imageUrl": "https://example.com/image2.jpg",
      "endImageUrl": "https://example.com/image2-end.jpg",
      "description": "blue ceramic mug",
      "externalId": "mug-2"
    }
  ]
}

Response

The response contains success to indicate the result of the response.

The success response contains two arrays:

• failedGenerations: List of generations that failed to start. Each item has an id (the index of the failure) and an error message.
• generations: List of successfully created predictions. Each item echoes back your externalId as external_id.

Example:

{
  "success": true,
  "data": {
    "failedGenerations": [
      {
        "id": "0",
        "error": "Failed to process start image: ..."
      }
    ],
    "generations": [
      {
        "id": 123,
        "user_id": "user-uuid",
        "status": "processing",
        "created_at": "2024-05-08T12:34:56.789Z",
        "updated_at": "2024-05-08T12:34:56.789Z",
        "external_id": "mug-2"
      }
    ]
  }
}

Error Handling

• If you do not have enough credits, you will receive an error response.
• If your request is invalid (e.g., missing fields), you will receive a validation error.
• If an image fails to process, it will appear in failedGenerations with an error message describing the cause.

Example error (insufficient credits):

{
  "success": false,
  "error": {
    "code": 3001,
    "message": "Insufficient credits for userId: [ID]",
    "meta": {
        "friendlyMessage": "You need 10 credits to perform this action. You currently have 0 credits.",
        "credits": 0,
        "requiredCredits": 10,
        "type": "error",
        "title": "Insufficient Credits",
        "userId": "[ID]"
    }
  }
}

Credits

Each generation consumes 5 credits.
Make sure your account has enough credits for the number of generations requested.

Example Usage

cURL

curl -X POST "https://rotateproduct.com/api/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generations": [
      {
        "imageUrl": "https://example.com/image1.jpg",
        "description": "red running shoe",
        "externalId": "shoe-1"
      },
      {
        "imageUrl": "https://example.com/image2.jpg",
        "description": "blue ceramic mug",
        "externalId": "mug-2"
      }
    ]
  }'

JavaScript (fetch)

const response = await fetch('https://rotateproduct.com/api/v1/generations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    generations: [
      {
        imageUrl: 'https://example.com/image1.jpg',
        description: 'red running shoe',
        externalId: 'shoe-1',
      },
      {
        imageUrl: 'https://example.com/image2.jpg',
        description: 'blue ceramic mug',
        externalId: 'mug-2',
      },
    ],
  }),
})

const data = await response.json()
console.log(data)

Best Practices

• Save your API key securely. It is only shown once when created.
• Track your generations using the externalId field for easier mapping of results.
• Check your credit balance before making bulk requests.
• Handle failed generations by checking the failedGenerations array in the response.

FAQ

Q: What happens if I lose my API key?
A: API keys are only shown once for security. If lost, delete the old key and create a new one in your API settings.

Q: How do I know when my video is ready?
A: Each successful generation is inserted with a status of processing. You can poll the predictions endpoint or set up a webhook to be notified when processing is complete.

When the generation completes, it will receive a succeeded status or failed status based on the result.

Q: What if I have more questions?
A: Contact our support team at info@rotateproduct.com.

Start automating your 3D product video creation with RotateProduct’s API today!