Soul ID creates and manages a custom reference from input images. Use the custom-reference endpoints below to create a Soul ID, check its processing status, list existing Soul IDs, or delete one.
1. Calling the API
Base URL: https://dev-api.higgsfield.com.
| Method | Endpoint | Operation |
|---|---|---|
| POST | /v1/custom-references | Create a Soul ID |
| GET | /v1/custom-references/list | List Soul IDs |
| GET | /v1/custom-references/{reference_id} | Get a Soul ID and its status |
| DELETE | /v1/custom-references/{reference_id} | Delete a Soul ID |
Setup
Keep credentials on the server and load them from environment variables. Replace the example image URL with a URL accessible to the API.
export HF_API_KEY_ID="YOUR_API_KEY_ID"
export HF_API_KEY_SECRET="YOUR_API_KEY_SECRET"Python examples use requests:
JavaScript examples use the built-in fetch API in a server environment.
2. Authentication
The endpoint definitions specify these headers:
| Header | Required by the schema | Value |
|---|---|---|
hf-api-key | Yes | API key ID (UUID) |
hf-secret | No | API key secret |
The examples send both credentials. Also send Content-Type: application/json when creating a Soul ID.
JavaScript setup
Run this setup before the JavaScript examples:
const baseUrl = "https://dev-api.higgsfield.com";
const headers = {
"hf-api-key": process.env.HF_API_KEY_ID,
"hf-secret": process.env.HF_API_KEY_SECRET,
};Python setup
Run this setup before the Python examples:
import os
import requests
base_url = "https://dev-api.higgsfield.com"
headers = {
"hf-api-key": os.environ["HF_API_KEY_ID"],
"hf-secret": os.environ["HF_API_KEY_SECRET"],
}3. Create a Soul ID
POST /v1/custom-references
Request parameters
| Parameter | Type | Required | Constraints |
|---|---|---|---|
name | string | Yes | Maximum 100 characters |
input_images | array of objects | Yes | Between 1 and 100 images |
input_images[].type | string | Yes | Must be image_url |
input_images[].image_url | string | Yes | Image URL |
Create examples
const response = await fetch(`${baseUrl}/v1/custom-references`, {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({
"name": "My Soul ID",
"input_images": [
{
"type": "image_url",
"image_url": "https://example.com/portrait.jpg"
}
]
}),
});
if (!response.ok) throw new Error(await response.text());
const soulId = await response.json();
const referenceId = soulId.id;Create response
A successful creation returns HTTP 200 with a Soul ID object. Save its id as reference_id for subsequent requests.
| Field | Type | Description |
|---|---|---|
id | UUID string | Soul ID identifier |
name | string | Reference name |
created_at | date-time string | Creation time |
status | string | Processing status; schema default is not_ready |
thumbnail_url | string or null | Reference thumbnail |
in_progress_at | date-time string or null | Processing start time |
4. Get a Soul ID and check status
GET /v1/custom-references/{reference_id}
Use the UUID from the creation response. Processing is asynchronous: repeat this GET request at intervals until status is completed or failed.
Status values
| Status | Meaning |
|---|---|
not_ready | Not ready for processing |
queued | Queued for processing |
in_progress | Processing is in progress |
completed | Processing completed |
failed | Processing failed |
Get examples
const referenceId = "YOUR_REFERENCE_ID";
const response = await fetch(
`${baseUrl}/v1/custom-references/${referenceId}`,
{ headers },
);
if (!response.ok) throw new Error(await response.text());
const soulId = await response.json();
console.log(soulId.status, soulId.reference_media);Get response
HTTP 200 returns the Soul ID fields described above and reference_media, an array of objects with id (UUID) and media_url (string).
5. List Soul IDs
GET /v1/custom-references/list
Query parameters
| Parameter | Type | Required | Default |
|---|---|---|---|
page | integer | No | 1 |
page_size | integer | No | 20 |
List examples
const response = await fetch(
`${baseUrl}/v1/custom-references/list?page=1&page_size=20`,
{ headers },
);
if (!response.ok) throw new Error(await response.text());
const page = await response.json();
console.log(page.items, page.total_pages);List response
HTTP 200 returns total, page, page_size, total_pages, and items. Each item contains a Soul ID object with the fields listed in the creation response.
6. Delete a Soul ID
DELETE /v1/custom-references/{reference_id}
Use the UUID of the Soul ID to delete.
Delete examples
const referenceId = "YOUR_REFERENCE_ID";
const response = await fetch(
`${baseUrl}/v1/custom-references/${referenceId}`,
{ method: "DELETE", headers },
);
if (!response.ok) throw new Error(await response.text());
// HTTP 204 has no JSON response body.Delete response
Successful deletion returns HTTP 204 with no response body.
7. Validation errors
The endpoint definitions document HTTP 422 for validation errors. Check the JSON body, required headers, path UUID, and query parameters against the schemas above.