POST /v1/influencers/:influencerId/reference-images

POST/v1/influencers/:influencerId/reference-images

Phase 1stable

Auth: Bearer
Scope: influencers:write

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 or inline upload); 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

influencerId
string (uuid)required
The influencer id.

Body

assetIds
string (uuid)[]required
Media asset ids. 1-20 per call.

Body is strict — assetIds is the only accepted field.

Request

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..."] }'

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();

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()

Responses

200Merged reference-image list.

{
  "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"
    }
  ]
}

422Validation — empty or >20 assetIds.

{
  "error": {
    "code": "VALIDATION",
    "message": "Invalid body.",
    "requestId": "req_...",
    "details": { "fieldErrors": { "assetIds": ["Array must contain at least 1 element(s)"] } }
  }
}

404Influencer not in this org.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Influencer not found.",
    "requestId": "req_..."
  }
}

Notes

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.

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

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