Skip to main content

​
POST /api/identify-product

Builds the meta-prompt for a brand and viewer profile, sends it to Google Gemini, and returns the specific product SKU Gemini selected along with the prompt that was used.
/api/ai/identify-product is an alias for this endpoint. Both paths accept identical request bodies and return identical responses.

​
Request body

​
brand_name
string
required
The brand to advertise. Gemini infers the best-fitting specific product from the viewer context.
​
user_data
object | string
Viewer context. Accepts a JSON object or a freeform string describing the viewer (demographics, interests, region, etc.).
​
mode
string
default:"full"
Prompt size. Must be "full" or "minimal". "full" produces a detailed prompt; "minimal" produces a shorter one.
​
output_language
string
Optional language for the output, e.g. "English" or "Spanish".
​
brand_voice_notes
string
Optional tone guidance, legal constraints, or words to avoid. Applied when Gemini selects the product.

​
Response

​
product_name
string
required
The specific product SKU Gemini selected for this viewer profile, e.g. "2025 Toyota RAV4 XLE Hybrid AWD".
​
prompt
string
required
The meta-prompt that was sent to Gemini.

​
Example

curl -X POST http://127.0.0.1:8000/api/identify-product \
  -H "Content-Type: application/json" \
  -d '{
    "brand_name": "Toyota",
    "user_data": {
      "household_income": "$75k-$100k",
      "interests": ["road trips", "outdoors"],
      "region": "US-West",
      "family_size": 2
    }
  }'
Response 
{
  "product_name": "2025 Toyota RAV4 XLE Hybrid AWD",
  "prompt": "You are a retail product specialist for Toyota..."
}

​
Errors

StatusCause
400brand_name is missing or empty.
400mode is not "full" or "minimal".
503GEMINI_API_KEY is not configured.
502Gemini request failed.

Build docs developers (and LLMs) love

Get started for freeTalk to us