Models

Models represent individual AI headshot sessions. Each team member who completes the onboarding process has an associated model that contains their generated photos.

List Models

Returns all AI models in your organization with pagination.

GET /organization/models

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Results per page (max 200)
`offset`	integer	0	Number of results to skip
`status`	string	-	Filter by model status
`teamId`	string	-	Filter by team ID

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/models?status=active&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js Example

const response = await fetch('https://server.headshotpro.com/api/v2/organization/models?status=active&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

const { models, pagination } = await response.json();

Response

{
  "success": true,
  "models": [
    {
      "id": "507f1f77bcf86cd799439011",
      "uid": "anon_abc123",
      "email": "john@example.com",
      "title": "John Doe",
      "status": "active",
      "teamId": "team_xyz789",
      "teamName": "Marketing",
      "isDevelopment": false,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "finishedAt": "2024-01-15T11:45:00.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 25,
    "offset": 0,
    "hasMore": true
  }
}

Model Status Values

Status	Description
`onboarding`	User is completing initial setup
`waiting`	User completed onboarding, waiting for training
`pending`	Model is being trained on photos
`generatingHeadshots`	Training complete, generating headshots
`active`	Headshots are ready
`failed`	Training or generation failed (auto-restarts)
`deleted`	Model has been deleted

Create Model (Whitelabel Only)

Creates an anonymous user and model for whitelabel integration. Returns a signed URL for embedding.

POST /organization/models

Requires: Whitelabel feature enabled on your organization.

Request Body

Field	Type	Required	Description
`email`	string	Yes	User's email address
`teamId`	string	No	Team to assign the user to
`isDevelopment`	boolean	No	Enable test mode (fast processing, no credit cost)

Request

curl -X POST "https://server.headshotpro.com/api/v2/organization/models" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "teamId": "team_xyz789",
    "isDevelopment": false
  }'

Node.js Example

const response = await fetch('https://server.headshotpro.com/api/v2/organization/models', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    teamId: 'team_xyz789',
    isDevelopment: false
  })
});

const { modelId, status, signedUrl } = await response.json();

Response

{
  "success": true,
  "modelId": "507f1f77bcf86cd799439011",
  "status": "onboarding",
  "signedUrl": "https://yourproheadshots.com/auth/social?token=AUTH_TOKEN&anonymous=1"
}

Development Mode

When isDevelopment: true:

Processing time reduced from ~1 hour to ~3 minutes
Uses test data instead of actual training
No credits consumed
Perfect for testing your integration

Error Responses

Status	Code	Description
400	`INVALID_REQUEST`	Invalid email format
400	`INVALID_REQUEST`	User with this email already exists
402	`INSUFFICIENT_CREDITS`	Not enough credits
403	`FORBIDDEN`	Whitelabel feature not enabled
404	`NOT_FOUND`	Team not found

Get Model Details

Returns detailed information about a specific model.

GET /organization/models/:modelId

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/models/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js Example

const response = await fetch('https://server.headshotpro.com/api/v2/organization/models/507f1f77bcf86cd799439011', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

const { model } = await response.json();

Response

{
  "success": true,
  "model": {
    "id": "507f1f77bcf86cd799439011",
    "uid": "anon_abc123",
    "email": "john@example.com",
    "title": "John Doe",
    "status": "active",
    "teamId": "team_xyz789",
    "teamName": "Marketing",
    "isDevelopment": false,
    "photoCount": 40,
    "favoritePhotoId": "507f1f77bcf86cd799439022",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "finishedAt": "2024-01-15T11:45:00.000Z",
    "signedUrl": "https://yourproheadshots.com/auth/social?token=AUTH_TOKEN&anonymous=1"
  }
}

Note: signedUrl is only included for whitelabel organizations.

Delete Model

Marks a model as deleted and removes the associated anonymous user.

DELETE /organization/models/:modelId

Request

curl -X DELETE "https://server.headshotpro.com/api/v2/organization/models/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Model deleted successfully",
  "modelId": "507f1f77bcf86cd799439011"
}

Notes

This action cannot be undone
Associated photos become inaccessible
A model.deleted webhook event is triggered