---
name: bulk-catalog
description: Shoots product catalogs with Icarus. Use when someone wants catalog, e-commerce or listing shots of one or many products from several angles (front, back, side, closeup, detail, macro), often copying the angles of a reference shoot, with product photos on a model, flat lay, body form or mannequin.
---

# Bulk catalog

## Overview

A catalog is every product shot in the same set of angles, on one model, on one background. Two facts drive everything below:

- Each side of a product holds details the others do not (a back print, a placket, a label). A shot keeps those details only when it pins the photo of the side it shows. Pinned on another side's photo, the details get invented.
- Icarus copies what it is given. A photo passed into a shot brings its item, its person and its colours with it. So a photo goes into a shot only when its pixels are what the shot needs; a pose goes in as words.

Every tool named below is on the Icarus connector (`Icarus:create_generations`, `Icarus:create_product` and so on).

## Sort every photo first

Look at every photo before any tool call, and put each one in one kind:

| Kind | What it looks like | What to do with it | Why |
|---|---|---|---|
| Product | the item to sell, one side, on a model, flat lay, body form or mannequin | upload, save as one product per side, pin on the shots of that side | pinning keeps its real colour, print and stitching |
| Pose reference | a front, back or side shot whose pose and framing the user wants copied, often of a different item | keep it out of the upload; write its pose, framing, crop and camera height into the prompts | passed in, its item and its model leak into the shot; words carry the pose without them |
| Closeup reference | a tight crop of one part (collar, buttons, fabric, logo) of a different item, whose crop the user wants copied | if some product being shot has no closeup photo of its own: upload it and pass its link in `referenceImageUrls` on that product's closeup shot only. If every product has its own closeup: keep it out of the upload and write its crop in words | a product's own closeup already shows the crop with the real fabric, so the reference would only add the wrong fabric. Without one, an exact crop is hard to describe in words, so the shot needs to see it |
| Model face | the person who should wear the products | upload and save with `create_character`, or pick theirs from `list_characters`; pin on every shot | one pinned face keeps the same person across the set |
| Background | an empty scene or backdrop | upload; pass its link in `referenceImageUrls` on every shot | the same link on every shot keeps the set on one background |

When the user says what a photo is for ("use image 4 as the model", "recreate the angles of 1 to 3"), take their word. A photo of a different item than the ones being shot, next to a request to copy its angles, is a pose or closeup reference.

If you cannot tell which kind a photo is, ask about that photo. A wrong guess spends credits on a set nobody can use.

Photos attached in this chat are the ones to shoot: upload and save them fresh, even when products with similar names are already saved. A saved product can hold a different or wrong picture, and pinning it puts that picture in every shot. Use saved products, characters or assets only when the person names saved items and attached none; then open each one's picture with `preview_image` and check it shows what its name says before pinning it.

To look at any Icarus link (an upload, a saved product, an asset, a shot), use `preview_image`. The app's own web reader cannot open Icarus links and fails on them.

## Steps

1. **Plan the set.** Angles = one per pose or closeup reference, or the angles the user named. If there are no references and they named no angles, ask which angles. Shots = every product times every angle.

   By default, recreate each reference as closely as you can: same pose, framing, crop and camera height. The user sent it because they want that angle, and matching angles is what makes a catalog look like one set. If they ask for variations ("a different pose", "give me options"), keep the angle (front stays front, closeup stays closeup) and change the pose, and say what you changed.

2. **Confirm and upload in one turn.** Write one short message: what each photo is, which model and background, and the shot list ("2 shirts x front, back, closeup = 6 shots"). Ask only about what is unclear. Then upload the products, the model face, the background, and the closeup reference only if some product has no closeup of its own:
   - If the host lets you pass their attached files, call `save_attached_files` with those photos.
   - Otherwise open `upload_file` as the only call in the turn and end the turn. Set `maxFiles` and `minFiles` to that number of photos, and list exactly those photos in the `note`.

3. **Match each link to its photo by looking at it.** Links from `upload_file` come back in the order the person picked the files, which is rarely the order of your note, and they carry no names. Call `preview_image` on every link, see what it shows, and pair it with the photo you sorted. A link paired by position turns the wall into a product and a shirt into the background. Links from `save_attached_files` come back in the order you sent them, so those need no check. If a link shows something you did not ask for, or a photo is missing, say so before saving.

4. **Save.** `create_product` once per product side, with that one link in `imageUrls` and the side in the name ("Blue shirt front", "Blue shirt back"). Save the model face with `create_character` unless they picked a saved one.

5. **Shoot the set in one `create_generations` call**, one request per shot:
   - `productIds`: the product of the side this angle shows (table below)
   - `characterIds`: the chosen model, the same on every request
   - `referenceImageUrls`: the background link; on the closeup shot of a product with no closeup of its own, the closeup reference link too
   - `prompt`: the roles sentence, the angle and the background, as in "Writing each prompt" below
   - `aspectRatio`: the reference photo's frame shape (a tall 2:3 photo stays 2:3), picked from the shapes `list_models` gives for the model; the same on every request. A different frame shape changes all the spacing, whatever the prompt says
   - `model` `nano-banana-pro` and `imageSize` `2K` on every request, unless the user names another model or size. One model and size across the set keeps the shots matching. If the model is refused, tell the user and ask which to use rather than swapping it silently
   - an `idempotencyKey` on the call, reused if you retry, so a retry does not charge twice

   One call takes up to 12 shots. For more, send the next 12 in a second call.

6. **Show the set.** `wait_generations` with every id, then `get_generations` with the whole set, in the same turn.

7. **Check each shot against its product photo.** Compare colour, print, logo and stitching. Name any shot that drifted and offer to reshoot it. A reshoot spends credits, so wait for a yes.

## Writing each prompt

The pinned product photo carries the product's look: colour, pattern, fabric, buttons. Leave the product out of the prompt. Words about the product compete with the photo, and where they disagree even slightly (a shade name, a button count), the shot follows the words and drifts from the real item.

The prompt carries only what no pinned picture shows: the angle and the background, in a few flowing sentences. It opens with one sentence that names each picture's job and locks the product without describing it:

**Roles:** "Use the pinned shirt as the product, exactly as in its photo, the pinned face as the model, and the backdrop picture as the background." On a closeup that passes a closeup reference, add "and the closeup picture for crop and framing only". Naming each picture's job keeps the model from mixing them up, and "exactly as in its photo" holds the product to the pin without a single word that could contradict it.

**Shot:** the reference's angle, measured off the reference photo so the new shot lands with the same spacing. A pose reference is never passed to the shot, so these words are all it gets:
- crop: where each edge of the frame cuts (top edge just above the hair, bottom edge at mid-thigh)
- space: headroom as a share of the frame (hair top about one tenth down from the top edge), space left and right of the body, and how much of the frame width the body fills (about half)
- placement: where the body sits (centred, or on the left third)
- camera: height (chest height), tilt (level, or looking slightly down), distance and lens feel (about 2 m away, 50 mm, no distortion)
- body: how far it is turned (square to camera, or a three-quarter turn to his left), head turn and tilt, where the eyes look, each arm and hand, which leg takes the weight
- focus: what is sharpest (the shirt)

Use camera terms for the shot size: "medium-full shot, centre-framed" for a knee-up, "macro lens, shallow depth of field" for a closeup. On a closeup, name what touches each edge (chin at the top edge, second button at the bottom edge, collar centred). When a closeup reference is passed, also say to copy its crop and framing only. Write the angle's shot line once and use it word for word for every product shot in that angle, so the blue and pink fronts match each other and the reference.

**Background:** the background and the light, one sentence, the same on every shot of the set.

## Which product photo for which angle

| Angle | Product side to pin |
|---|---|
| Front, three-quarter front | front |
| Back, three-quarter back | back |
| Side | side; without one, the nearer of front or back, and say which you used |
| Closeup, detail, macro | the product's own closeup if they sent one; otherwise the side that shows that part (collar, placket, buttons: front; back yoke: back) |

A back angle needs the back photo of that product. If it is missing, ask for it: from the front photo alone the back gets invented.

## Examples

<example>
Photos: 1 navy polo front, 2 navy polo back, 3 navy polo collar closeup, 4 a man's face, 5 empty beige backdrop, 6 blue shirt front, 7 pink shirt front, 8 pink shirt back, 9 blue shirt back.
Request: "Use 4 as the model and 5 as the background. Recreate the angles of 1 to 3 for 6 and 7, and add their backs. 4K."

- Sort: 1 and 2 are pose references, 3 is a closeup reference, 6 to 9 are products, 4 is the model, 5 is the background.
- Message: "Shooting the blue and pink shirts in the three polo angles (front, back, collar closeup) on him, on the beige backdrop, 4K: 6 shots. Upload these 7 photos." `upload_file` with `maxFiles` 7, note "blue front, blue back, pink front, pink back, the face, the backdrop, the collar closeup".
- After Continue: `preview_image` on each of the 7 links to see which photo each one is.
- Save four products and one character.
- `create_generations`, 6 requests, each with the character, the backdrop link, `model` nano-banana-pro and `imageSize` 4K:
  - blue front, `aspectRatio` 2:3 like the polo photos: "Use the pinned shirt as the product, exactly as in its photo, the pinned face as the model, and the backdrop picture as the background. Medium-full shot, centre-framed. Front view, body square to camera, head straight, eyes to the lens, both hands in trouser pockets, weight even on both legs. Frame cut just above the hair and at mid-thigh, hair top about one tenth down from the top edge, body centred and filling about half the frame width. Camera at chest height, level, 50 mm look with no distortion. Plain beige studio backdrop, soft even daylight."
  - blue back: the shot line is measured off the polo back photo the same way (facing away, arms relaxed at sides, same crop edges, headroom and camera)
  - blue closeup, plus the closeup link: "Use the pinned shirt as the product, exactly as in its photo, the pinned face as the model, the backdrop picture as the background, and the closeup picture for crop and framing only. Macro lens closeup copying that crop and framing: collar and top buttons, chin at the top edge. Plain beige studio backdrop, soft even daylight."
  - the same three for pink, pinning the pink products, with the same words

If the user had also sent a collar closeup of each shirt, those two would be saved as products ("Blue shirt closeup", "Pink shirt closeup") and pinned on the closeup shots, and photo 3 would stay out of the upload: its crop goes in the prompt as words. The upload would be 8 photos: 6 shirt photos, the face, the backdrop.
</example>

<example>
Photos: 1 black tote bag front on a table, 2 its back on a table.
Request: "Catalog of this bag, front and back, on Aria, white background."

- Sort: 1 and 2 are products. No references, no background photo. Aria is a saved model.
- Message: "Shooting the black tote front and back, carried by Aria, plain white background: 2 shots." `save_attached_files` with both photos.
- Save "Black tote front" and "Black tote back". Find Aria with `list_characters`.
- `create_generations`, 2 requests with Aria and one bag side each. No reference links; the background goes in the prompt: "... plain white seamless studio background".
</example>

<example>
Photos: 1 green kurta front on a mannequin, 2 a woman's face.
Request: "Front, back and sleeve detail of the kurta on her."

- Sort: 1 is a product (front only), 2 is the model. The back angle has no back photo, and no background was given.
- Message: "I can shoot the front and the sleeve detail from the front photo. For the back I need a photo of the kurta's back, or it gets invented. Which background should I use?" Wait for the answers before shooting.
</example>

## Common mistakes

| Mistake | What happens | Do this |
|---|---|---|
| Pose reference passed into a shot | its item or its model shows up in the output | write its pose in words, keep it out of the tool calls |
| Closeup reference left out when a product has no closeup of its own | the closeup crop comes out wrong | upload it and pass it on that product's closeup shot |
| Closeup reference uploaded when every product has its own closeup | an extra upload, and its fabric can leak in | pin the product's own closeup, write the crop in words |
| Closeup shot without a product pin | the reference's fabric and colour get copied | pin the product and say to copy only the crop |
| Closeup angle skipped because the product has no closeup photo | the set is missing an angle | pin the side that shows that part |
| Back shot pinned on the front photo | the back comes out invented | pin the back photo, or ask for it |
| Prompt says "same pose as image 1" | the shot cannot see image 1 and guesses | describe the pose, crop and camera |
| Shot line says only "front view, knee-up" | the spacing, crop and camera drift from the reference and from the other shots | measure crop, headroom, placement, camera and body off the reference, and set `aspectRatio` to its shape |
| Saved products reused while the person attached new photos | an old or wrong picture gets pinned, like a wall saved as a shirt | upload and save the attached photos fresh |
| Icarus link opened with the app's web reader | it fails and the shoot stalls | open it with `preview_image` |
| Uploaded links paired with photos by their position | the wall gets saved as a product, a shirt gets sent as the background | `preview_image` every uploaded link and pair it by what it shows |
| Prompt describes the product (shade, pattern, button count) | the shot follows the words over the pinned photo and the product drifts | leave the product to the pin; the prompt holds the roles sentence, the angle and the background |
| Asking about something the user already said | an extra round trip | take their word, ask only what is unclear |
| One `create_generation` per shot in a loop | slower, and a retry can charge twice | one `create_generations` call for the set |

---

Page: https://withicarus.com/skills/bulk-catalog
Download: https://onai.b-cdn.net/skills/bulk-catalog/v1-e69d4201/bulk-catalog.zip
Install guide for AI apps: https://withicarus.com/skills/bulk-catalog/llms-install.md
This skill makes photos and videos with Icarus. Connect Icarus to your AI app: https://withicarus.com/mcp