Morface API Quickstart

This page walks through the production path most integrations need: create an API key, prepare public media URLs, submit a job with an input object, receive webhook completion events, and fetch the final result URL.

Before you begin

• Create a key in Account -> API Keys.
• Store the key in your backend secret manager.
• Use Authorization: Bearer <api_key> on every /api/v1 request.
• Host your input media at public http/https URLs reachable by Morface.
• Treat the API as asynchronous. Successful submit responses mean the job was accepted.

1. Create an API key

Create the key from API Keys. Morface shows the full key only once, so save it immediately.

export MORFACE_API_KEY="sk_live_..."

2. Prepare public media URLs

Public submit bodies only accept public http/https media URLs.

• Single-file slots use a single URL string.
• Multi-file slots use an array of URL strings.
• Private temp/... paths and verificationToken objects are not accepted by /api/v1.
• Media fields and params must be nested inside the top-level input object.

3. Choose your base URL and submit path

Use a single base URL for all public API calls:

export MORFACE_API_BASE="https://www.morface.ai/api/v1"

For submit requests, append the job-specific path using job_type:

$MORFACE_API_BASE/jobs/submit/<job_type>

For example, job_type=image-face-swap maps to:

$MORFACE_API_BASE/jobs/submit/image-face-swap

4. Submit a job

curl -X POST "$MORFACE_API_BASE/jobs/submit/image-face-swap" \
  -H "Authorization: Bearer $MORFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-swap-001" \
  -d '{
    "job_type": "image-face-swap",
    "model": "facex/image-face-swap",
    "input": {
      "source": "https://cdn.example.com/source.jpg",
      "target": "https://cdn.example.com/target.jpg"
    },
    "webhook": {
      "url": "https://example.com/morface/webhook",
      "secret": "whsec_demo"
    }
  }'

Use an Idempotency-Key whenever your backend might retry the same submit on timeouts or network errors.

5. Handle terminal webhooks

Morface only sends terminal webhook events:

• job.completed
• job.failed
• job.cancelled

Each request may include:

• X-Morface-Event-Id
• X-Morface-Timestamp
• X-Morface-Signature

The signature format is:

hex(hmac_sha256(secret, timestamp + "." + rawBody))

6. Keep polling as a fallback

Even if you use webhooks, keep a status and result fallback path in case your webhook endpoint is unavailable.

Check status:

curl "$MORFACE_API_BASE/jobs/<uuid>/status" \
  -H "Authorization: Bearer $MORFACE_API_KEY"

Fetch the signed result URL:

curl "$MORFACE_API_BASE/jobs/<uuid>/result" \
  -H "Authorization: Bearer $MORFACE_API_KEY"

7. Minimal client examples

Node.js

const API_BASE = "https://www.morface.ai/api/v1";

const response = await fetch(`${API_BASE}/jobs/<uuid>/status`, {
  headers: {
    Authorization: `Bearer ${process.env.MORFACE_API_KEY}`,
  },
});

const json = await response.json();
console.log(json);

Python

import requests

API_BASE = "https://www.morface.ai/api/v1"

response = requests.get(
    f"{API_BASE}/jobs/<uuid>/status",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30,
)

print(response.json())

Next pages

• Authentication
• Jobs
• Webhooks
• Error and Idempotency Rules