Predictions API

Predictions are AI-generated images that place your products in custom environments based on text prompts. This is where the magic happens - transforming simple descriptions into photorealistic product visualizations.

Create a Prediction

Generate an AI image featuring your product in a custom environment.

Endpoint

POST /prediction/

Request Parameters

Parameter	Type	Required	Description
product_id	string	✅	ID of a LoRA-enabled product
prompt	string	✅	Text description of the desired scene
aspect_ratio	string	✅	Image dimensions ratio

Supported Aspect Ratios

Ratio	Orientation	Best For
16:9	Landscape	Website banners, social media covers
3:2	Landscape	Traditional photography, print ads
5:4	Almost square	Instagram posts, print materials
1:1	Square	Instagram, profile images, thumbnails
4:5	Portrait	Instagram stories, mobile screens
2:3	Portrait	Posters, magazine covers
9:16	Vertical	TikTok, Instagram stories, mobile

Request Example

curl -X POST https://app.veez.ai/api/prediction/ \
  -H "Authorization: Bearer $YOUR_API_TOKEN" \
  -F "product_id=3d26a5823201fe71a0730ac457b4d91a" \
  -F "prompt=A premium coffee package sitting on a rustic wooden table in a cozy café, warm morning light streaming through the window" \
  -F "aspect_ratio=16:9"

Response

{
  "id": "8c3052e4cf29cf7ec04b56ff1fe128f8",
  "product_id": "3d26a5823201fe71a0730ac457b4d91a",
  "date_modification": "2025-04-11 15:40:53",
  "prompt": "A premium coffee package sitting on a rustic wooden table in a cozy café, warm morning light streaming through the window",
  "aspect_ratio": "16:9",
  "status": "processing",
  "images": []
}

Processing Time

Predictions typically take 30-60 seconds to generate. The images array will be populated once processing is complete.

List Predictions

Retrieve all predictions from your account.

Endpoint

GET /prediction/

Request Example

curl -s -H "Authorization: Bearer $VEEZAI_API_TOKEN" \
  https://app.veez.ai/api/prediction/

Response

[
  {
    "id": "8c3052e4cf29cf7ec04b56ff1fe128f8",
    "product_id": "7edbadd4f7cabdd5654ea718a5a7c657", 
    "date_modification": "2025-04-11 15:40:53",
    "prompt": "une canette dans arbre",
    "images": [
      "https://apptest.veez.ai/record/8c3052e4cf29cf7ec04b56ff1fe128f8/prediction/out-0.png"
    ]
  }
]

Response Fields

Field	Type	Description
id	string	Unique prediction identifier
product_id	string	Associated product ID
date_modification	string	Last update timestamp
prompt	string	Text prompt used for generation
images	array	URLs of generated images (empty while processing)

Get Prediction Details

Retrieve a specific prediction with its generated images.

Endpoint

GET /prediction/{prediction_id}

Parameters

Parameter	Type	Required	Description
prediction_id	string	✅	The prediction ID from create or list response

Request Example

curl -s -H "Authorization: Bearer $VEEZAI_API_TOKEN" \
  https://app.veez.ai/api/prediction/8c3052e4cf29cf7ec04b56ff1fe128f8

Response

{
  "id": "8c3052e4cf29cf7ec04b56ff1fe128f8",
  "product_id": "7edbadd4f7cabdd5654ea718a5a7c657",
  "date_modification": "2025-04-11 15:40:53", 
  "prompt": "une canette dans arbre",
  "aspect_ratio": "1:1",
  "images": [
    "https://apptest.veez.ai/record/7807/prediction/out-0.png",
    "https://apptest.veez.ai/record/7807/prediction/out-1.png"
  ]
}

Writing Effective Prompts

Prompt Structure

The best prompts follow this pattern:

[Product context] + [Environment] + [Lighting/Mood] + [Style/Quality]

Examples

Good Prompts ✅

# Detailed and specific
"A luxury perfume bottle on a marble vanity in an elegant bathroom, soft natural lighting, high-end photography style"

# Context-rich environment  
"Organic coffee beans package displayed in a modern kitchen with concrete countertops, morning sunlight, minimalist aesthetic"

# Atmospheric description
"Smartphone case on a wooden desk in a creative studio, warm Edison bulb lighting, artistic workspace vibe"

Poor Prompts ❌

# Too vague
"product on table"

# Contradictory elements
"luxury item in cheap environment"

# Overly complex
"floating in space while underwater with fire and ice simultaneously"

Prompt Categories

Lifestyle & Context

• "in a modern living room"
• "on a kitchen counter during breakfast"
• "in a professional office setting"
• "at a outdoor picnic"

Lighting Conditions

• "soft morning light"
• "dramatic studio lighting"
• "warm golden hour"
• "bright natural daylight"

Style & Mood

• "minimalist aesthetic"
• "rustic and cozy"
• "high-end luxury"
• "industrial modern"

Photography Style

• "professional product photography"
• "lifestyle photography"
• "editorial style"
• "commercial advertising"

Advanced Techniques

Multiple Variations

Generate several images with slight prompt variations:

# Base prompt
base="Premium coffee package on wooden table"

# Variations
curl -X POST https://app.veez.ai/api/prediction/ \
  -F "product_id=$PRODUCT_ID" \
  -F "prompt=$base, morning light, cozy café" \
  -F "aspect_ratio=16:9"

curl -X POST https://app.veez.ai/api/prediction/ \
  -F "product_id=$PRODUCT_ID" \
  -F "prompt=$base, dramatic lighting, modern kitchen" \
  -F "aspect_ratio=16:9"

Batch Generation Script

#!/bin/bash
TOKEN="your_token_here"
PRODUCT_ID="your_product_id"

prompts=(
  "luxury product on marble surface, studio lighting"
  "casual lifestyle setting, natural light" 
  "outdoor environment, golden hour lighting"
  "modern office desk, clean aesthetic"
)

for prompt in "${prompts[@]}"; do
  curl -X POST https://app.veez.ai/api/prediction/ \
    -H "Authorization: Bearer $TOKEN" \
    -F "product_id=$PRODUCT_ID" \
    -F "prompt=$prompt" \
    -F "aspect_ratio=1:1"
  
  sleep 5  # Avoid rate limits
done

Monitoring Generation Progress

#!/bin/bash
check_prediction_status() {
  local prediction_id=$1
  local token=$2
  
  while true; do
    response=$(curl -s -H "Authorization: Bearer $token" \
      https://app.veez.ai/api/prediction/$prediction_id)
    
    images=$(echo $response | jq -r '.images | length')
    
    if [ "$images" -gt "0" ]; then
      echo "Prediction $prediction_id completed!"
      echo $response | jq -r '.images[]'
      break
    else
      echo "Still processing..."
      sleep 10
    fi
  done
}

# Usage
check_prediction_status "prediction_id_here" "your_token"

Error Responses

400 Bad Request - Missing Product

{
  "error": "Bad Request",
  "message": "product_id is required"
}

400 Bad Request - Invalid Aspect Ratio

{
  "error": "Bad Request",
  "message": "aspect_ratio must be one of: 16:9, 3:2, 5:4, 1:1, 4:5, 2:3, 9:16"
}

403 Forbidden - LoRA Not Ready

{
  "error": "Forbidden",
  "message": "Product does not have LoRA enabled. Generate LoRA first."
}

404 Product Not Found

{
  "error": "Not Found",
  "message": "Product with ID xyz does not exist"
}

Best Practices

Prompt Optimization

• Be specific about environment and mood
• Include lighting conditions for better results
• Use professional photography terms for higher quality
• Test variations to find what works best

Quality Guidelines

• Start simple before trying complex scenes
• Use consistent style across related predictions
• Consider your brand guidelines when writing prompts
• Review results and refine prompts based on output

Rate Limiting

• Wait between requests to avoid hitting limits
• Monitor response times and adjust accordingly
• Use batch scripts for multiple predictions
• Implement retry logic for failed requests

Next Steps

Now that you can create predictions:

1. Explore Examples - See complete workflows
2. Advanced Techniques - Learn pro tips and tricks
3. Download and use your images for marketing and content creation

Creative Ideas

Try seasonal themes, lifestyle contexts, or brand-specific environments to create unique marketing content that stands out!