Build with the Phase Pal model library

Browse public models, fetch account-owned assets, and create short-lived signed URLs for model files through a simple versioned API.

Create your first key

Send the API key in the Authorization header. Keys are account-owned and can read only your own private library.Create a free API key

Server-side by design

Developer API keys are intended for server-to-server calls. Do not put keys in browser code; the alternate X-PhasePal-API-Key header is server-only.

Base URL

https://api.phasepal.com

Quickstart

Create a key from your dashboard, keep it server-side, then call the model API with a Bearer token.

List public models

curl https://api.phasepal.com/v1/models \
  -H "Authorization: Bearer pp_live_xxx"

List your account models

curl https://api.phasepal.com/v1/me/models \
  -H "Authorization: Bearer pp_live_xxx"

Next.js Route Handler

// app/api/phasepal-models/route.ts
export async function GET() {
  const response = await fetch("https://api.phasepal.com/v1/models", {
    headers: {
      Authorization: `Bearer ${process.env.PHASEPAL_API_KEY}`,
    },
  });

  return Response.json(await response.json(), { status: response.status });
}

Python server script

import os
import requests

response = requests.get(
    "https://api.phasepal.com/v1/me/models",
    headers={"Authorization": f"Bearer {os.environ['PHASEPAL_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Authentication

Send the API key in the Authorization header. Keys are account-owned and can read only your own private library.

Developer API keys are intended for server-to-server calls. Do not put keys in browser code; the alternate X-PhasePal-API-Key header is server-only.

Model endpoints

GET /v1/models lists public Phase Pal models.
GET /v1/models/{id} returns one model by id.
POST /v1/models/{id}/download-url returns a short-lived file URL when your account has access.
GET /v1/me/models lists your uploaded, purchased, downloaded, and saved models.
GET /v1/me/usage returns API usage for the current key.

Your account library

The API includes uploaded, purchased, downloaded, and saved model relationships. Private models remain visible only to the account that owns them.

Store API keys only on your server.

Do not commit keys to GitHub or bundle them into client apps.

Signed model URLs expire quickly and should not be cached publicly.

Age-restricted models include age_restricted: true so your app can apply its own audience controls.

Example response

{
  "object": "list",
  "data": [
    {
      "object": "phasepal.model",
      "id": "model_123",
      "name": "Example Avatar",
      "visibility": "public",
      "age_restricted": false,
      "entitlement": {
        "can_request_download_url": true,
        "reason": "free"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_123"
}

Model file URLs

Model files are returned only through explicit signed-url calls. URLs are short lived, private, and preserve paid-entitlement and download-disabled checks.

Create a signed file URL

curl -X POST https://api.phasepal.com/v1/models/model_123/download-url \
  -H "Authorization: Bearer pp_live_xxx"

Pricing and limits

The developer API is free at launch. Requests are still rate limited and metered for reliability, abuse detection, and product analytics.

Catalog reads: 120 requests per minute per key.
Private library reads: 60 requests per minute per key.
Signed URL creation: 30 requests per minute per key.
Signed model URLs expire within 5 minutes.

Errors

Errors use a stable envelope with type, code, message, param, request_id, and error_id fields.

400 invalid_request_error for invalid limits, cursors, or validation errors.
401 invalid_api_key for missing, malformed, disabled, revoked, expired, or unknown keys.
403 insufficient_scope, download_disabled, signed_urls_disabled, or entitlement_required.
429 rate_limit_exceeded with Retry-After and X-RateLimit headers.
500 internal_error with request_id and error_id.

Example error

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "param": null,
    "request_id": "req_123",
    "error_id": null
  }
}