# POST /v1/influencers/:influencerId/reference-images (/docs/api/reference/influencers/reference-images)



<Endpoint method="POST" path="/v1/influencers/:influencerId/reference-images" scope="influencers:write" phase="1" />

Attaches 1-20 media asset ids to the influencer's `referenceImages`. Synchronous — no job envelope. The assets must already exist in the same project (via [presign + finalize](/docs/api/reference/media/presign-upload) or [inline upload](/docs/api/reference/media/upload-media-inline)); this endpoint only links them.

Already-attached ids are deduped on `assetId`. Asset ids from other projects silently drop out of the result (they aren't errors — just missing from the saved list).

## Path parameters [#path-parameters]

<Parameters
  rows="[
  { name: 'influencerId', type: 'string (uuid)', required: true, description: 'The influencer id.' },
]"
/>

## Body [#body]

<Parameters
  title="Body"
  rows="[
  { name: 'assetIds', type: 'string (uuid)[]', required: true, description: 'Media asset ids. 1-20 per call.' },
]"
/>

Body is strict — `assetIds` is the only accepted field.

## Request [#request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```sh title="terminal"
    curl -X POST \
      https://api.layers.com/v1/influencers/{influencerId}/reference-images \
      -H "X-Api-Key: $LAYERS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "assetIds": ["asset_01HXZ9...", "asset_01HY0AB..."] }'
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="bind-reference.ts"
    const res = await fetch(
      `https://api.layers.com/v1/influencers/${influencerId}/reference-images`,
      {
        method: 'POST',
        headers: {
          'X-Api-Key': process.env.LAYERS_API_KEY!,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ assetIds: [assetId] }),
      },
    );
    const { referenceImages } = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```py title="bind_reference.py"
    import os, httpx

    r = httpx.post(
        f"https://api.layers.com/v1/influencers/{influencer_id}/reference-images",
        headers={
            "X-Api-Key": os.environ["LAYERS_API_KEY"],
            "Content-Type": "application/json",
        },
        json={"assetIds": [asset_id]},
    )
    data = r.json()
    ```
  </Tab>
</Tabs>

## Responses [#responses]

<Response status="200" description="Merged reference-image list.">
  ```json
  {
    "influencerId": "inf_01HXZ9...",
    "referenceImages": [
      {
        "assetId": "asset_01HXZ9...",
        "url": "https://media.layers.com/.../ava-01.jpg",
        "thumbnailUrl": "https://media.layers.com/.../ava-01-thumb.jpg",
        "addedAt": "2026-04-18T09:25:10Z"
      }
    ]
  }
  ```
</Response>

<Response status="422" description="Validation — empty or >20 assetIds.">
  ```json
  {
    "error": {
      "code": "VALIDATION",
      "message": "Invalid body.",
      "requestId": "req_...",
      "details": { "fieldErrors": { "assetIds": ["Array must contain at least 1 element(s)"] } }
    }
  }
  ```
</Response>

<Response status="404" description="Influencer not in this org.">
  ```json
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Influencer not found.",
      "requestId": "req_..."
    }
  }
  ```
</Response>

## Notes [#notes]

<Callout type="info">
  Ids that don't resolve to an asset in the influencer's project are
  silently dropped. The response only lists ids that were successfully
  attached, so inspect `referenceImages` to confirm what persisted.
</Callout>

* **Idempotent at the list level.** Reposting the same `assetIds` refreshes their `addedAt` but doesn't duplicate entries. Use `Idempotency-Key` for full replay semantics.
* **Max 20 per call, 1 minimum.** There's no per-influencer cap in this endpoint, but practical identity quality plateaus after \~5.

## Errors [#errors]

| Code              | When                            |
| ----------------- | ------------------------------- |
| `VALIDATION`      | Empty array, >20 ids, bad uuid. |
| `NOT_FOUND`       | Influencer not in this org.     |
| `FORBIDDEN_SCOPE` | Key lacks `influencers:write`.  |

## See also [#see-also]

* [Upload media](/docs/api/reference/media/upload-media-inline)
* [Create an influencer](/docs/api/reference/influencers/create-influencer)
* [Read the influencer](/docs/api/reference/influencers/get-influencer)