curl -X POST "https://api.example.com/api/v1/product-images" \
-H "Content-Type: application/json" \
-d '{
"productId": 101,
"imageUrl": "https://example.com/images/sofa-front.jpg",
"altText": "Modern grey sofa - front view",
"displayOrder": 1
}'
Method and Path
POST /api/v1/product-images
Request Body
ID of the product this image belongs to
URL of the product image. Must be a valid and accessible URL.
Alternative text description for accessibility. Recommended for SEO and compliance.
Order in which the image should be displayed. Lower numbers appear first. If not specified, the image will be added at the end.
Response
The newly created product image object
Unique identifier for the product image (auto-generated)
ID of the product this image belongs to
Alternative text description for accessibility
Order in which the image should be displayed
Response Codes
Product image successfully created. The response includes a Location header with the URL of the new resource.
Invalid request body or validation error
Request Example
{
"productId": 101,
"imageUrl": "https://example.com/images/sofa-front.jpg",
"altText": "Modern grey sofa - front view",
"displayOrder": 1
}
Response Example
{
"id": 1,
"productId": 101,
"imageUrl": "https://example.com/images/sofa-front.jpg",
"altText": "Modern grey sofa - front view",
"displayOrder": 1
}
HTTP/1.1 201 Created
Location: /api/v1/product-images/1
Content-Type: application/json
Error Response Example
{
"status": 400,
"error": "Bad Request",
"message": "Validation failed",
"errors": [
{
"field": "productId",
"message": "Product ID is required"
},
{
"field": "imageUrl",
"message": "Image URL is required"
}
]
}
Usage Examples
Create Product Image with All Fields
curl -X POST "https://api.example.com/api/v1/product-images" \
-H "Content-Type: application/json" \
-d '{
"productId": 101,
"imageUrl": "https://example.com/images/sofa-front.jpg",
"altText": "Modern grey sofa - front view",
"displayOrder": 1
}'
Create Product Image with Minimal Fields
curl -X POST "https://api.example.com/api/v1/product-images" \
-H "Content-Type: application/json" \
-d '{
"productId": 101,
"imageUrl": "https://example.com/images/sofa-side.jpg"
}'
Create Product Image with JavaScript
const imageData = {
productId: 101,
imageUrl: 'https://example.com/images/sofa-front.jpg',
altText: 'Modern grey sofa - front view',
displayOrder: 1
};
fetch('https://api.example.com/api/v1/product-images', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(imageData)
})
.then(response => response.json())
.then(data => console.log('Created:', data))
.catch(error => console.error('Error:', error));
Create Product Image with Python
import requests
image_data = {
'productId': 101,
'imageUrl': 'https://example.com/images/sofa-front.jpg',
'altText': 'Modern grey sofa - front view',
'displayOrder': 1
}
response = requests.post(
'https://api.example.com/api/v1/product-images',
json=image_data
)
if response.status_code == 201:
created_image = response.json()
print(f"Created image with ID: {created_image['id']}")
else:
print(f"Error: {response.status_code}")
Best Practices
- Image URLs: Ensure image URLs are accessible and point to optimized images for web display
- Alt Text: Always provide descriptive alt text for better accessibility and SEO
- Display Order: Use consistent increments (e.g., 1, 2, 3) to make reordering easier
- Multiple Images: When adding multiple images for a product, set appropriate display orders to control the sequence