> ## 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.

# Extract a brand asset

> Turn one finished marketing piece into its design system: colors, type, layout, logo, and elements, measured from its pixels

Send one finished marketing piece, such as a billboard, a poster, or an Instagram story, and get back its design system: the colors and how much of each, the type, where the logo and headline sit, and how much room the piece leaves. Give it to your agents so the pieces they create follow how the brand designs its campaigns.

## Extract a piece

Upload the image as `multipart/form-data` in a field named `file`:

```bash theme={null}
curl -X POST https://api.tastelabs.com/design/submissions/brand-asset \
  -H "X-API-Key: $TASTE_API_KEY" \
  -F "file=@billboard.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 design system from [`GET /design/submissions/{id}/result`](https://docs.tastelabs.com/api-reference/endpoint/get-submission-result).

Send a PNG, JPEG, or WebP of up to 20 MB and 40 megapixels, one per request. The image can be the flat creative, a mockup, or a photo of the piece where it runs; a mockup or a photo is straightened and cropped to the creative before anything is measured.

> [!NOTE]
>
> Each submission costs 2 credits, refunded when the extraction fails. Every upload is a fresh extraction: results are never served from cache.

The piece is sorted into one of these mediums. When it is a close call, `medium.unsure` is `true`.

| `medium.value` | The piece |
| - | - |
| `billboard` | An out-of-home billboard. |
| `poster` | A printed poster, portrait or near-square. |
| `ig_story` | A 9:16 Instagram or social story. |
| `ig_post` | A square or 4:5 Instagram or social feed post. |
| `social_post` | A landscape feed post or link card, as on LinkedIn, X, or Facebook. |
| `google_ad` | A display ad in a standard banner size. |

## What fails

A failed submission's `error` tells you what to do, and its credits are refunded:

| `error` starts with | Meaning |
| - | - |
| `NOT_A_BRAND_ASSET` | Not a finished marketing piece: a logo on its own, a photo with no copy designed on it, a website or app screen, an email, a slide, or several pieces on one board. Send another image. |
| `UNREADABLE_IMAGE` | The image could not be read. Send another image. |
| `EXTRACTION_FAILED` | The extraction did not finish. Retry the same request. |

## Read the result

This illustrative example comes from a fictional coffee brand's Instagram post. This is not a complete result, it is an illustrative example.

```json theme={null}
{
  "kind": "brand_asset",
  "id": "e8f5fcee-7b3a-4c1d-9e26-5f0a8d4b2c71",
  "status": "completed",
  "source_url": "file://fernway-ig-post.png",
  "medium": "ig_post",
  "original": { "url": "https://storage.example.com/e8f5fcee/brand_asset/original.png", "content_type": "image/png" },
  "flat": { "url": "https://storage.example.com/e8f5fcee/brand_asset/flat.jpg", "content_type": "image/jpeg" },
  "result": {
    "medium": { "value": "ig_post", "unsure": false },
    "format": { "width": 1080, "height": 1080, "aspect_ratio": 1.0, "closest": "square post", "size": "1080×1080 px" },
    "profile": {
      "brand_name": "Fernway",
      "primary_purpose": "direct_response",
      "main_cta": "Order a bag",
      "copy_tone": ["Calm", "Warm", "Assured"]
    },
    "colors": {
      "board": [
        { "name": "Cream", "type": "Neutral", "hex": "#F4EDE3", "rules": { "description": "75.0% of the board", "when_to_use": ["background", "text"] } },
        { "name": "Dark Brown", "type": "Neutral", "hex": "#2B1D14", "rules": { "description": "11.3% of the board", "when_to_use": ["graphic", "text", "logo"] } },
        { "name": "Peach", "type": "Warm Color", "hex": "#E9B98F", "rules": { "description": "11.1% of the board", "when_to_use": ["graphic"] } },
        { "name": "Rust", "type": "Warm Color", "hex": "#C2562F", "rules": { "description": "1.8% of the board", "when_to_use": ["graphic"] } }
      ],
      "contrast_pattern": [
        { "type": "dark type", "ground": "neutral ground", "contrast": "5.66–14.02:1", "applies_to": ["body_copy", "headline", "logo"] },
        { "type": "light type", "ground": "saturated ground", "contrast": "4.5:1", "applies_to": ["cta"] }
      ]
    },
    "typography": {
      "titles": {
        "variants": [
          {
            "name": "Fraunces",
            "role": "headline",
            "used_on": ["headline"],
            "specs": { "size": "cap height 7.13% of board height", "font_weight": "600" },
            "colors": ["#2B1D14"],
            "case": "sentence",
            "classification": "Serif / Old Style",
            "stand_in": { "family": "Fraunces", "weight": 600, "alternatives": ["DM Serif Display", "Gloock"] },
            "technical": { "font_family_css": "\"Fraunces\", serif" },
            "confidence": "high"
          }
        ]
      }
    },
    "elements": {
      "items": [
        {
          "segment": "headline",
          "entity": "headline",
          "placement": "middle-left",
          "bbox": { "x0": 73, "y0": 521, "x1": 672, "y1": 722 },
          "width_pct_of_board": 59.9,
          "text": "Slow mornings,\nbrewed right.",
          "words": 4
        },
        {
          "segment": "website",
          "entity": "cta",
          "kind": "url",
          "placement": "bottom-right",
          "text": "fernway.example",
          "words": 0,
          "urls": ["fernway.example"]
        }
      ],
      "count": 5,
      "not_on_board": ["imagery", "qr_code"]
    },
    "layout": {
      "structure": {
        "alignment_axes": [
          { "edge": "left", "at_pct_of_width": 7.4, "elements": ["headline", "body", "button_shape", "logo"] },
          { "edge": "right", "at_pct_of_width": 92.8, "elements": ["website", "circle"] }
        ]
      },
      "whitespace_pct": 59.6
    },
    "not_measured": ["font of body: letterforms too small or soft to identify"]
  }
}
```

`original` is the image as you sent it, and `flat` is the flat creative the measurements were taken on. Positions and sizes are percentages of the piece, and `bbox` values run from 0 to 1000 across its width and height. Empty values are left out, so a missing field means the piece does not have it.

| Field | Meaning |
| - | - |
| `medium`, `format` | What the piece is and its nearest standard size. |
| `profile` | Brand name, the piece's goal, its main call to action, and the tone of its copy. |
| `colors` | Every color by share of the piece, where it is used, and the contrast of its type. |
| `typography` | Each type style: size, weight, case, color, and the closest open font in `stand_in`. |
| `surfaces`, `graphic_devices` | Solid fills, gradients as CSS, grain, and decorative shapes. |
| `elements` | Every element, such as the logo, headline, call to action, and images, with its text verbatim. |
| `layout` | Alignment, logo clear space, whitespace, the medium's safe zone, and the spacing of the text stack. |
| `assets` | The logo and each image cut from the piece. |
| `not_measured` | What could not be measured, and why. |

## Use cases

* **From a website extraction**: send the billboards, posters, and social posts from a website extraction's [brand assets](https://docs.tastelabs.com/concepts/brand-assets.md), one per request. Your agent learns how the brand designs each medium, not just its site.
* **Across several pieces**: extract several of a brand's pieces and read the results together. The colors, spacing, and layout that hold across pieces become the brief for new ones.
* **To check a new piece**: extract it too and compare the two results field by field.


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