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:

• id (string, optional): A unique identifier for tracking within your systems (recommended).
• imageUrl (string): The URL of the product image.
• description (string): A short description of the product.

{
  "generations": [
    {
      "imageUrl": "https://example.com/image1.jpg",
      "description": "red running shoe",
      "id": "shoe-1"
    },
    {
      "imageUrl": "https://example.com/image2.jpg",
      "description": "blue ceramic mug",
      "id": "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.
• generations: List of successfully created predictions.

Example:

{
  "success": true,
  "data": {
    "failedGenerations": [
      {
        "id": "shoe-1"
      }
    ],
    "generations": [
      {
        "id": 123,
        "user_id": "user-uuid",
        "status": "rotating",
        "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, its id will appear in failedGenerations.

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",
        "id": "shoe-1"
      },
      {
        "imageUrl": "https://example.com/image2.jpg",
        "description": "blue ceramic mug",
        "id": "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',
        id: 'shoe-1',
      },
      {
        imageUrl: 'https://example.com/image2.jpg',
        description: 'blue ceramic mug',
        id: '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 id 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 rotating. 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!