> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tastelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Profile a brand's photography

> Turn a brand's photos into the traits they share and the tone measured from their pixels

Use a photography profile to tell your agents what a brand's photos look like, so the images they create or pick match the brand's photography and not just its colors and type. Each photo is read against a fixed schema of 45 fields (light, framing, subject, color, finish, and more) and its pixels are measured; the photos are then merged into one profile.

A photography profile is a submission like a [website extraction](https://docs.tastelabs.com/concepts/submissions.md) or a [brand kit](https://docs.tastelabs.com/concepts/brand-kit.md), but it takes photos instead of a URL or a PDF, and its result has `kind: "photography"` and its own shape.

## Build a profile

Send 1 to 12 photos, each as a public `https://` `url` or as `image_b64` (PNG, JPEG, or WebP):

```bash theme={null}
curl -X POST https://api.tastelabs.com/design/submissions/photography \
  -H "X-API-Key: $TASTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "photos": [
      {"url": "https://images.example.com/campaign-1.jpg"},
      {"url": "https://images.example.com/campaign-2.jpg"},
      {"url": "https://images.example.com/campaign-3.jpg"}
    ]
  }'
```

The API returns `202` with a `submission_id`. Poll [`GET /design/submissions/{id}`](https://docs.tastelabs.com/api-reference/endpoint/get-submission) until `status` is `completed` or `failed`, then read the profile from [`GET /design/submissions/{id}/result`](https://docs.tastelabs.com/api-reference/endpoint/get-submission-result). A profile usually takes under a minute.

Photography profiles appear in [`GET /design/submissions`](https://docs.tastelabs.com/api-reference/endpoint/list-submissions) next to other submissions; filter them with `?kind=photography`. A profile's `source_url` is the first photo's URL, or `upload://` followed by the photo count when the photos were uploaded.

> [!NOTE]
>
> Each submission costs 2 credits, refunded when no profile comes back. Every request is a fresh profile: profiles are never served from cache.

### How many photos to send

* **One photo**: the profile is that photo's own reading.
* **Two or more**: `rules` keeps the values most of the photos share; with two photos, that is what both share. The rest goes to `varies`.

Send 3 to 8 photos that represent the brand for a profile you can generalize from.

### Use cases

* **From a brand kit**: give your agent a [brand kit](https://docs.tastelabs.com/concepts/brand-kit.md), have it take the brand's photos from the kit, and send them to the photography endpoint. The profile it gets back describes how the brand's photos look, so the new photography your agent creates stays aligned with the brand.
* **From a website**: do the same with a [website extraction](https://docs.tastelabs.com/concepts/submissions.md). Send the site's images and use the profile to create, for example, a new subpage whose photography matches the rest of the site. Any graphics or illustrations among those images are left out on their own.

## What is left out

Every photo is read, but only photographs are merged. A photo that reads as a graphic or illustration, a photoreal render, or a composite is left out of the profile, and its outcome says why in `excluded`. Photos that cannot be used, such as an unreachable URL or a file that is not an image, come back as `invalid`.

When no photo is left to merge, the submission fails and the credits are refunded. Its `error` tells you what to do:

| `error` starts with | Meaning |
| - | - |
| `NOT_ENOUGH_PHOTOS` | None of the photos is a usable photograph. Send other photos. |
| `PHOTO_READS_FAILED` | The photos could not be read. Retry the same request. |

> [!NOTE]
>
> The result endpoint returns `409 NOT_READY` until the profile is `completed`, including for a failed submission. Read the outcome from [`GET /design/submissions/{id}`](https://docs.tastelabs.com/api-reference/endpoint/get-submission).

## Read the result

The following example comes from six Ai2 photos. Most rules, variations, and outcomes are omitted.

```json theme={null}
{
  "kind": "photography",
  "id": "5fb12de2-b640-4333-954a-a41703406b9a",
  "status": "completed",
  "photos": 6,
  "profile": {
    "photos": 4,
    "rules": [
      { "field": "focal_structure", "name": "Focal structure", "value": "single_dominant", "share": 0.75 },
      { "field": "vignette", "name": "Vignette", "value": "none", "share": 1.0 }
    ],
    "varies": [
      { "field": "shot_scale", "name": "Shot scale and crop margin", "values": { "close": 2, "detail": 2 } }
    ],
    "tone": [
      { "field": "exposure_key", "name": "Exposure key", "value": "mid_key", "measure": 47.29 }
    ],
    "signature": { "darkest_lightness": 1.6, "brightest_lightness": 95.0, "colourfulness": 72.0, "lightness_spread": 24.9 },
    "palette": ["#1f1914", "#504745", "#e3e2e1", "#dc9912", "#e9b73f"]
  },
  "outcomes": [
    { "index": 1, "status": "read", "main_subject": "A single yellow sunflower head with a dark central disc, seen face-on", "excluded": null },
    { "index": 3, "status": "read", "main_subject": "Undulating glossy wave surface filling the frame; no discrete object", "excluded": "photoreal_render" }
  ]
}
```

| Field | Meaning |
| - | - |
| `photos` | Photos sent. `profile.photos` counts the ones merged. |
| `profile.rules` | Values most of the merged photos share, each with its `share`. |
| `profile.varies` | Fields where no value is shared enough to be a rule, with the number of photos per value. |
| `profile.tone` | Exposure, highlights, contrast, and other tone values, measured from the pixels and never read by a model. `measure` is the median the value was cut from. |
| `profile.signature` | How the photos render, as medians: black and white points, clipped highlights, warmth of mid-tones and shadows, colourfulness, and contrast. |
| `profile.palette` | Dominant colors of the photos. These are not brand colors. |
| `outcomes` | One entry per photo sent, in order: whether it was `read`, `invalid`, or `failed`, what it shows, and why it was `excluded`. |

## Give it to your agents

Hand your agent `profile.rules` and `profile.tone` as the brief for new imagery, and `profile.varies` as what it is free to change. Ask it to check its output against the rules, the same way it checks copy against a brand kit's `rules`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.