Identity Check API

Identity Check API

The Identity Check API is the core integration point for platforms. Use it before allowing users to create AI avatars.

Check Single Identity

Check if a name and image match a protected identity.

Endpoint

POST /v1/lmif/identity/check

Request

SDK

const result = await lmif.identity.check({
  name: "Taylor Swift",
  imageUrl: "https://example.com/avatar.jpg"
});

cURL

curl -X POST https://api.lookmaimfamous.com/v1/lmif/identity/check \
  -H "Authorization: Bearer lmif_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Taylor Swift",
    "imageUrl": "https://example.com/avatar.jpg"
  }'

Request Body

Field	Type	Required	Description
name	string	Yes	Name of the identity to check
imageUrl	string	Yes	URL of the avatar image
description	string	No	Avatar description (improves detection)
context	string	No	Additional context (platform, use case)

Response

{
  "isBoxed": true,
  "isClaimed": true,
  "confidence": 0.95,
  "matchedIdentity": {
    "claimId": "claim_xyz789",
    "boxId": "box_abc123",
    "name": "Taylor Swift",
    "variations": ["T. Swift", "Taylor Alison Swift"],
    "entityType": "INDIVIDUAL",
    "verificationTier": "GOLD"
  },
  "policy": "MONETIZE",
  "policyDetails": {
    "royaltyRate": 0.10,
    "revenueTypes": ["subscription", "per_message", "tips"],
    "contentGuidelines": "https://..."
  },
  "detection": {
    "layer": 1,
    "classification": "EXACT_MATCH",
    "parodyLikelihood": 0.02
  },
  "action": "TRACK_REVENUE"
}

Response Fields

Field	Type	Description
isBoxed	boolean	Whether the identity is protected
isClaimed	boolean	Whether the identity is claimed (verified)
confidence	number	Detection confidence (0-1)
matchedIdentity	object	Details of the matched identity
policy	string	Protection policy if boxed
policyDetails	object	Policy-specific configuration
detection	object	Detection system details
action	string	Recommended action for platform

Recommended Actions

Action	Meaning	What to Do
ALLOW	No protection	Proceed normally
BLOCK	Identity blocked	Prevent avatar creation
REQUIRE_LICENSE	License required	Redirect to licensing flow
TRACK_REVENUE	Revenue share required	Create avatar, enable tracking
VERIFY_COMMERCIAL	Check commercial status	Ask user about commercial intent
REVIEW_PARODY	Possible parody	Allow with parody disclaimer

Check Multiple Identities (Batch)

Check multiple identities in a single request.

Endpoint

POST /v1/lmif/identity/check/batch

Request

SDK

const results = await lmif.identity.checkBatch([
  { name: "Celebrity A", imageUrl: "https://..." },
  { name: "Celebrity B", imageUrl: "https://..." },
  { name: "Celebrity C", imageUrl: "https://..." }
]);

cURL

curl -X POST https://api.lookmaimfamous.com/v1/lmif/identity/check/batch \
  -H "Authorization: Bearer lmif_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "identities": [
      { "name": "Celebrity A", "imageUrl": "https://..." },
      { "name": "Celebrity B", "imageUrl": "https://..." },
      { "name": "Celebrity C", "imageUrl": "https://..." }
    ]
  }'

Request Body

Field	Type	Required	Description
identities	array	Yes	Array of identity objects
identities[].name	string	Yes	Name to check
identities[].imageUrl	string	Yes	Image URL
identities[].id	string	No	Your internal ID (returned in response)

Note

Batch requests are limited to 100 identities per request.

Response

{
  "results": [
    {
      "id": "your_internal_id_1",
      "name": "Celebrity A",
      "isBoxed": true,
      "policy": "BLOCK_ALL",
      "action": "BLOCK"
    },
    {
      "id": "your_internal_id_2",
      "name": "Celebrity B",
      "isBoxed": false,
      "action": "ALLOW"
    },
    {
      "id": "your_internal_id_3",
      "name": "Celebrity C",
      "isBoxed": true,
      "policy": "MONETIZE",
      "royaltyRate": 0.15,
      "action": "TRACK_REVENUE"
    }
  ],
  "meta": {
    "total": 3,
    "boxed": 2,
    "unprotected": 1,
    "processingTime": 245
  }
}

Implementation Examples

Basic Integration

async function checkBeforeCreating(name: string, imageUrl: string) {
  const result = await lmif.identity.check({ name, imageUrl });

  switch (result.action) {
    case 'ALLOW':
      return { allowed: true };

    case 'BLOCK':
      return {
        allowed: false,
        message: 'This identity is protected and cannot be used'
      };

    case 'REQUIRE_LICENSE':
      return {
        allowed: false,
        requiresLicense: true,
        licenseUrl: `/license/${result.matchedIdentity.boxId}`
      };

    case 'TRACK_REVENUE':
      return {
        allowed: true,
        tracking: {
          boxId: result.matchedIdentity.boxId,
          royaltyRate: result.policyDetails.royaltyRate
        }
      };

    case 'VERIFY_COMMERCIAL':
      return {
        allowed: 'pending',
        question: 'Will this avatar be used for commercial purposes?'
      };

    default:
      return { allowed: false };
  }
}

With Error Handling

async function safeIdentityCheck(name: string, imageUrl: string) {
  try {
    const result = await lmif.identity.check({ name, imageUrl });
    return result;
  } catch (error) {
    if (error.code === 'RATE_LIMITED') {
      // Wait and retry
      await sleep(error.retryAfter * 1000);
      return safeIdentityCheck(name, imageUrl);
    }

    if (error.code === 'VALIDATION_ERROR') {
      // Log and fail gracefully
      console.error('Invalid request:', error.details);
      return { action: 'ALLOW' }; // Fail open
    }

    // Unknown error - fail closed
    console.error('Identity check failed:', error);
    return { action: 'BLOCK', reason: 'Service unavailable' };
  }
}

Best Practices

1. Check before creation - Always check identity before allowing avatar creation
2. Cache appropriately - Results can be cached for up to 1 hour
3. Handle all actions - Implement handlers for all possible actions
4. Include context - Providing description and context improves detection
5. Use batch for imports - When importing existing avatars, use batch API
6. Implement retry logic - Handle rate limits gracefully

Tip

For real-time avatar creation flows, the Identity Check API typically responds in under 100ms for Layer 1 matches.

Error Responses

Code	Description
INVALID_IMAGE_URL	Image URL is invalid or inaccessible
IMAGE_TOO_LARGE	Image exceeds size limit (10MB)
INVALID_NAME	Name is empty or invalid
BATCH_TOO_LARGE	Batch exceeds 100 identities