---
title: "Model photoshoot"
method: POST
path: "/api/photoshoot/v3/generate"
tags: ["Photoshoot"]
---

# Model photoshoot

`POST /api/photoshoot/v3/generate`

## Request

- Base URL: `https://api.crayonz.ai`
- URL: `https://api.crayonz.ai/api/photoshoot/v3/generate`
- Auth: API key in header `X-API-Key`

Editorial photos of a real-looking model wearing your design. Pass the transparent design and, for a faithful print, the front mockup from /api/mockup/render. Pick a vibe (skater, streetwear, minimal, gym, festival, …) or ask /api/photoshoot/recommend-vibes first. Returns one URL per shot with the pose, cast and location used; check succeeded against requested.

## Request body

- object
  - `design_reference_url` string, required: Public https URL of the transparent design PNG (file_url from /api/design/custom)
  - `front_side` object: { mockup_url, design_url } for the front of the garment — mockup_url should be the /api/mockup/render output so the print is placed exactly
  - `back_side` object: Same shape as front_side, for back-print designs
  - `garment_type` string: tshirt, oversized_tshirt, hoodie, zipper_hoodie, polo, acid_wash_tshirt
  - `garment_color_hex` string: Garment colour as #rrggbb
  - `garment_color_name` string: Garment colour name, used in the prompt
  - `pattern` 'front' | 'back': Which side carries the print
  - `vibe` string: streetwear, minimal, grit, y2k, kinfolk, editorial, hiphop, sports_fan, festival, academia, techwear, gym, retro_90s, beach, punk, outdoor_adventure, anime_otaku, skater, corporate_casual, college_campus, funny, casual_kickback, date_night, gamer, music_scene, football_fan, cricket_fan, f1_fan, basketball_fan
  - `shot_count` integer: 1–6 shots; the default rotation is front hero, back view, detail
  - `shot_types` string[]: Optional per-shot types, same length as shot_count: front_hero, back_view, detail_context, mirror_selfie, phone_selfie, disposable_cam, polaroid, duo_matching, friends_group, couple, crowd_solo, …
  - `seed` integer: Repeat a batch with the same casting and locations

## Response `200`

Success

- object
  - `shots` object[]: One entry per successful shot: shot_type, url, pose_used, cast_used, location_used, cost_usd
  - `requested` integer: shot_count from the request
  - `succeeded` integer: How many of the requested shots actually came back — check this against requested
  - `failure_reason` string, nullable: Set when succeeded < requested; null otherwise
  - `model_used` string

## Other responses

- `401`: Unauthorized — invalid or missing API key
- `402`: Insufficient credits
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/crayonz/apis/crayonz-api.md) · [All operations](https://skmtc.dev/crayonz/apis/crayonz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crayonz/apis/crayonz-api/revisions/1114c84167b2?raw)