API > Integrate API into your product > Filter Creator API Endpoints

How to use Alias IDs in your integration

This page explains what Alias IDs are, why they exist, and how to use them in your code so that your design team can swap filter content at any time — without touching production code or involving developers.

1. What is an Alias ID?

An Alias ID is a stable UUID that acts as a pointer to an AI Filter. Instead of hardcoding a filter UUID directly in your application, you hardcode the Alias ID. Your design team can then change which filter the Alias points to via the Filter Creator Webapp — no code changes, no redeployment needed.

Without aliases:
Your code references filter a1b2c3d4-... directly. Changing the filter means changing your code and redeploying.

With aliases:
Your code references alias x9y8z7w6-.... Your design team swaps the underlying filter in the webapp. Your code keeps working with the same ID.

2. How it works

┌──────────────┐        ┌──────────────┐        ┌──────────────┐
│  Your Code   │───────▶│  Alias ID    │───────▶│  AI Filter   │
│  (hardcoded) │        │  (stable)    │        │  (swappable) │
└──────────────┘        └──────────────┘        └──────────────┘
                              │
                        Design team changes
                        this mapping via the
                        Filter Creator Webapp

A designer creates a filter in the Filter Creator Webapp.
They create an Alias and assign the filter to it — see How to set up an Alias in the Filter Creator.
They share the Alias ID (UUID) with your development team.
You hardcode the Alias ID in your application.
At runtime, your code resolves the alias to get the current filter ID, then uses that filter ID with the generation endpoints.
When the design team wants to change the content, they swap the filter in the webapp. Your code keeps using the same alias.

3. Endpoint Reference

Purpose – Method – Path

List all your aliases → GET /api/alias/
Get a single alias (resolve it) → GET /api/alias/{alias\_id}/
Create a new alias → POST /api/alias/
Update an alias (swap filter) → PATCH /api/alias/{alias\_id}/
Delete an alias → DELETE /api/alias/{alias\_id}/

🔐 Authentication
All requests require a valid Bearer token. Include it in the Authorization header:

Authorization: Bearer <your_access_token>

4. Resolving an Alias in your code

This is the most common operation. Your application calls this at runtime to find out which filter the alias currently points to.

4.1. Request

GET /api/alias/{alias_id}/
Authorization: Bearer <your_access_token>

4.2. Response

{
  "id": "x9y8z7w6-1234-5678-abcd-ef0123456789",
  "ai_filter": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "ai_filter_data": {
    "label": "Summer Party Neon"
  },
  "project": "Summer Campaign 2025",
  "user": "designer@yourcompany.com",
  "created_at": "2025-06-01T10:00:00Z",
  "updated_at": "2025-07-15T14:30:00Z",
  "last_used": "2025-07-20T09:15:00Z",
  "history": [
    {
      "ai_filter_id": "old-filter-uuid-here",
      "ai_filter_name": "Spring Party Glow",
      "time_removed": "2025-07-15T14:30:00Z"
    }
  ]
}

Key fields:

id → The Alias ID (the one you hardcode)
ai\_filter → The current filter UUID to use with generation endpoints
ai\_filter\_data.label → Human-readable name of the current filter
history → Previous filters that were assigned (for audit trail)

5. Using the resolved filter ID

Once you have the ai_filter UUID from the alias response, use it with any generation endpoint exactly as you would use a regular filter ID:

POST /v1/run/faceswap
{
  "filter_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "image": "<base64_encoded_image>"
}

See:

6. Integration Example

Here is a typical integration pattern. Your code resolves the alias once, then uses the filter ID for generation.

Step 1 – Resolve the alias

import requests

ALIAS_ID = "x9y8z7w6-1234-5678-abcd-ef0123456789"  # hardcoded, shared by design team
API_BASE = "https://ai-filters.eventstation.ai"

headers = {"Authorization": f"Bearer {access_token}"}

# Resolve alias to get current filter ID
alias_response = requests.get(
    f"{API_BASE}/api/alias/{ALIAS_ID}/",
    headers=headers
)
alias_data = alias_response.json()
filter_id = alias_data["ai_filter"]

Step 2 – Use the filter ID for generation

# Use the resolved filter ID with your generation endpoint
job_response = requests.post(
    f"{API_BASE}/v1/run/faceswap",
    headers=headers,
    json={
        "filter_id": filter_id,
        "image": base64_encoded_image
    }
)
job_id = job_response.json()["id"]

Step 3 – Poll for result

status_response = requests.post(
    f"{API_BASE}/v2/status/{job_id}",
    headers=headers
)
result = status_response.json()
# result["output"]["images"][0] contains the base64 image

7. Creating an Alias via API

While aliases are typically created in the Filter Creator Webapp, you can also create them programmatically.

Request

POST /api/alias/
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "ai_filter": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "project": "Summer Campaign 2025"
}

ai\_filter (required) → UUID of the filter to point to
project (optional) → Project or campaign name to organize aliases

Response

{
  "id": "newly-generated-alias-uuid",
  "ai_filter": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "ai_filter_data": {
    "label": "Summer Party Neon"
  },
  "project": "Summer Campaign 2025",
  "user": "you@yourcompany.com",
  "created_at": "2025-07-20T10:00:00Z",
  "updated_at": "2025-07-20T10:00:00Z",
  "last_used": null,
  "history": []
}

📝 Important: Save the returned id — this is the Alias ID you will hardcode in your application.

8. Updating an Alias (swapping the filter)

When the design team swaps a filter via the webapp, this is what happens under the hood. You can also do it via API:

PATCH /api/alias/{alias_id}/
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "ai_filter": "new-filter-uuid-here",
  "project": "Updated Campaign Name"
}

The previous filter is automatically recorded in the history array. No data is lost.

9. Listing all Aliases

To see all aliases available to your account:

GET /api/alias/
Authorization: Bearer <your_access_token>

Returns an array of alias objects. Useful for debugging or building admin tools.

10. Best Practices

Hardcode alias IDs, not filter IDs. This is the whole point — alias IDs never change, filter assignments do.
Resolve at runtime. Always fetch the alias before generating, so you get the latest filter assignment.
Cache with a TTL. If you generate many images per second, cache the resolved filter ID for a short period (e.g. 5 minutes) to avoid unnecessary API calls.
Use project names. Organize aliases by campaign or project so your team can manage them easily.
Coordinate with your design team. Share alias IDs via your internal project management. The design team can find them in the Filter Creator Webapp under the Aliases section.

11. Troubleshooting

The alias returns a different filter than expected

This is expected behavior — someone on your team likely swapped the filter via the Filter Creator Webapp. Check the history field to see previous assignments.

404 when resolving an alias

Verify the alias ID is correct (it is a UUID format)
Confirm your access token has permission to access this alias
The alias may have been deleted

I want to know when a filter was last changed

Check the updated\_at field on the alias. For the full change history, inspect the history array.