FunPhantom API Documentation

Domain: https://funphantom.in/api/

Authentication: Single X-API-Key header on every request.

Catalog: API generation does not filter prompts. On this host, GET /templates returns the curated catalog. Use nsfw.funphantom.in for the complete list.

Table of Contents

1. Getting Started
2. Authentication
3. Rate Limits
4. Common Headers & Response Format
5. Error Codes
6. User Endpoints
7. Template & Catalog Endpoints
8. Generation Endpoints
9. Job Status & Management
10. Delete Endpoints
11. Catalog & Domain Notes
12. Code Examples
13. FAQ

1. Getting Started

1.1 What You Can Do

The FunPhantom API exposes the same generation capabilities available on the website:

• Video Generation (WAN 2.2): Image-to-video from an input photo
• Video + Audio (LTX): Text-to-video or image-to-video with synced audio
• MiniMax H3: Text-to-video, image-to-video, and reference-to-video
• Wan 3.0 Ref2V: Reference-to-video (1–5 images) with optional audio / prompt expansion
• Image Generation (T2I): Flux text-to-image
• Image Edit: Blend/edit images using base64 inputs
• Image Inpaint: Mask-based inpainting
• Faceswap: Face swap onto a target image (Pro subscription required)
• Job Management: Submit jobs, poll status, list jobs, delete jobs, reuse settings
• Template Catalogs: LoRA video templates, image models, image-edit templates, H3 R2V templates

1.2 Request Flow

1. Authenticate with X-API-Key: fp_your_key on every request.
2. For POST endpoints, send Content-Type: application/json with your parameters and base64-encoded images.
3. Receive a job_id in the submit response.
4. Poll GET /api/job/{job_id} every 5–10 seconds until status is COMPLETED or FAILED.

Status reads are database-only — the API does not call RunPod on your behalf. A background worker handles processing and billing.

2. Authentication

2.1 API Key Format

Your API key is a single opaque token:

X-API-Key: fp_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abc

Send it in the X-API-Key header on every request. There is no second secret and no request signing (HMAC).

2.2 Obtaining an API Key

API keys are generated from the FunPhantom dashboard under Account → API Keys. You will only see the full key once at creation — save it immediately.

2.3 Using Your Key

Python Example

import requests

API_KEY = "fp_your_api_key_here"
BASE_URL = "https://funphantom.in/api"

HEADERS = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# GET request
r = requests.get(f"{BASE_URL}/user/info", headers=HEADERS)
print(r.json())

# POST request
payload = {
    "prompt": "a cinematic video",
    "image_base64": "data:image/jpeg;base64,...",
    "duration": 6
}
r = requests.post(f"{BASE_URL}/generate/video", headers=HEADERS, json=payload)
print(r.json())

JavaScript Example

const API_KEY = 'fp_your_api_key_here';
const BASE_URL = 'https://funphantom.in/api';

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json'
};

const payload = { prompt: 'a cinematic video', image_base64: 'data:image/jpeg;base64,...', duration: 6 };
const resp = await fetch(`${BASE_URL}/generate/video`, { method: 'POST', headers, body: JSON.stringify(payload) });
console.log(await resp.json());

2.4 Important Notes

• All requests (GET and POST) require X-API-Key.
• Never embed your API key in client-side code or public repositories.
• Keys can be deleted and rotated from the API Dashboard.

3. Rate Limits

Rate limits are enforced per IP and per API key:

When exceeded:

{
  "error": "Too many requests. Please slow down.",
  "code": 429
}

4. Common Headers & Response Format

4.1 Required Headers

4.2 Submit Response Format

Generation endpoints return a JSON object like:

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "submitted",
  "message": "Video generation started successfully (1.2 tokens used)",
  "token_cost": 1.2,
  "remaining_tokens": 48.8
}

Some endpoints add type-specific fields (see §8).

4.3 Base64 Image Format

Images may be sent as:

• Raw base64 string
• Data URI: data:image/jpeg;base64,/9j/4AAQ…
• Public HTTPS URL (where supported)

5. Error Codes

All errors return JSON:

{
  "error": "Human-readable message",
  "code": 400
}

6. User Endpoints

6.1 GET /api/user/info

Returns the authenticated user's profile.

Response:

{
  "id": 42,
  "email": "[email protected]",
  "username": "myuser",
  "first_name": "Jane",
  "last_name": "Doe",
  "tokens": 48.8,
  "subscription_active": true,
  "subscription_end": "2026-12-31T00:00:00",
  "created_at": "2025-06-01T10:00:00"
}

Internal fields (is_boss, password_hash, OAuth tokens) are never exposed.

6.2 GET /api/user/balance

Response:

{
  "tokens": 48.8,
  "subscription_active": true,
  "subscription_end": "2026-12-31T00:00:00",
  "can_generate": true
}

6.3 GET /api/user/tokens

Response:

{
  "tokens": 48.8,
  "total_tokens_used": 152.3,
  "subscription_active": true
}

7. Template & Catalog Endpoints

7.1 GET /api/templates

List WAN 2.2 LoRA / video templates. Alias: GET /api/lora-templates.

Responses include full prompt text so API clients can display or override prompts before generating.

Response:

{
  "templates": {
    "blink_missionary": {
      "id": "blink_missionary",
      "name": "Blink Missionary",
      "category": "Dance",
      "subcategory": null,
      "is_mature": false,
      "usage_count": 152,
      "release_date": "2025-01-15",
      "is_new": false,
      "is_featured": true,
      "prompt": "A woman dancing…",
      "negative_prompt": "blurry, low quality…",
      "description": "Short description for UI",
      "hint": "Upload a clear full-body photo",
      "sub_templates": [
        {
          "id": "close_up",
          "name": "Close-up",
          "prompt": "Close-up variation prompt…",
          "negative_prompt": "…"
        }
      ]
    }
  },
  "count": 42
}

On this host, templates with is_mature: true (or category filtered by catalog rules) are omitted from the list.

Boss-only: GET /api/templates?full=1 returns raw template JSON plus a categories object.

7.2 GET /api/image-models

List text-to-image models for POST /api/generate/image.

Response:

{
  "success": true,
  "models": {
    "flux_dev": {
      "id": "flux_dev",
      "name": "Flux Dev",
      "description": "Default Flux model",
      "type": "image",
      "has_lora": false
    }
  }
}

7.3 GET /api/image-edit-templates

Response:

{
  "success": true,
  "templates": {
    "oil_painting": {
      "id": "oil_painting",
      "name": "Oil Painting",
      "category": "Style",
      "description": "Transform into oil painting",
      "requires_second_image": false,
      "usage_count": 89
    }
  }
}

7.4 GET /api/h3-r2v-templates

MiniMax H3 reference-to-video template catalog.

Query params: sort (latest | most-used | free-first | name), id (single template).

API-key clients always receive template prompts.

List response:

{
  "templates": {
    "cinematic_walk": {
      "id": "cinematic_walk",
      "name": "Cinematic Walk",
      "category": "Motion",
      "prompt": "…",
      "usage_count": 34
    }
  },
  "categories": ["Motion", "Dance"],
  "sort": "latest",
  "pro_prompt_lock_enabled": false
}

Single template (?id=cinematic_walk):

{
  "template": { "id": "cinematic_walk", "name": "Cinematic Walk", "prompt": "…" },
  "pro_prompt_lock_enabled": false
}

8. Generation Endpoints

8.1 POST /api/generate/video

Alias: POST /api/generate

Image-to-video (WAN 2.2).

Submit response:

{
  "job_id": "uuid",
  "status": "submitted",
  "message": "Video generation started successfully (1.2 tokens used)",
  "token_cost": 1.2,
  "remaining_tokens": 47.6,
  "result_type": "url",
  "video_quality": "legacy"
}

8.2 POST /api/generate/video-audio

Alias: POST /api/video-audio/generate

Text-to-video or image-to-video with audio.

I2V is unlocked for API keys (no Pro gate on this route).

Submit response:

{
  "job_id": "uuid",
  "status": "submitted",
  "message": "Video+Audio generation started (4.5 tokens used)",
  "token_cost": 4.5,
  "remaining_tokens": 43.1,
  "mode": "T2V"
}

8.3 POST /api/generate/image-edit

Submit response:

{
  "job_id": "uuid",
  "status": "submitted",
  "token_cost": 0.5,
  "remaining_tokens": 42.6
}

8.4 POST /api/generate/image

Flux text-to-image.

Submit response:

{
  "job_id": "uuid",
  "status": "submitted",
  "token_cost": 0.4,
  "remaining_tokens": 42.2
}

8.5 POST /api/generate/minimax-h3

Aliases: POST /api/minimax-h3/generate

With template_id + mode=i2v, the server prepends an identity-preservation preamble and attaches the template’s style LoRAs. With template_id and no mode (or t2v), mode defaults to r2v.

Do not send loras, lora_name, style_lora, or lora_pairs — style LoRAs are resolved from template_id server-side.

Post-deploy smoke checklist: docs/H3_TEMPLATE_I2V_SMOKE.md.

Submit response:

{
  "job_id": "uuid",
  "status": "submitted",
  "message": "MiniMax H3 T2V generation started (6.0 tokens reserved)",
  "pre_token_cost": 6.0,
  "token_cost": 6.0,
  "remaining_tokens": 36.2,
  "mode": "t2v",
  "reference_count": 0
}

Dedicated status: GET /api/minimax-h3-jobs/{id}

8.5b POST /api/generate/wan3-ref2v

Aliases: POST /api/wan3-ref2v/generate

Wan 3.0 Reference-to-Video. Requires an active Pro subscription. Fixed token billing from size × duration (audio and prompt expansion are free).

*Multipart image uploads are also accepted. Multipart audio: audio_1 … audio_3 or audios[].

Tokens: max(2, round(duration × rate[size], 2)) — rates 0.88 / 1.76 / 3.52 per second for 480p / 720p / 1080p. Optional job_discounts.wan3_ref2v. Reference audio does not add tokens.

Submit response:

{
  "job_id": "uuid",
  "status": "submitted",
  "message": "Wan 3.0 Ref2V generation started (8.0 tokens used)",
  "token_cost": 8.0,
  "remaining_tokens": 40.0,
  "status_url": "https://funphantom.in/wan3-ref2v-job/uuid"
}

Poll: GET /api/wan3-ref2v-jobs/{id} — completed jobs include video_base64 and API-key video_url (/api/wan3-ref2v/{id}/video).

8.5c POST /api/generate/seedream-i2i

Seedream 5.0 Pro image edit. Requires Pro subscription. Multipart (seedream_image_0 … seedream_image_4 or images) or JSON images as data-URIs/base64. 1–5 images, 4 MB each.

Tokens: round(usd × 27, 2) at 2× Siray USD, pack 675 tokens = $50. Default 1.22 per image ($0.045 API). Optional extra-ref USD from admin. Optional job_discounts.seedream_5_pro_i2i.

Poll: GET /api/seedream-jobs/{id} — image: GET /api/seedream-jobs/{id}/image

8.5d POST /api/generate/seedream-ref2i

Seedream 4.5 reference-to-image. Same image payload. Sizes are 2K-only (no 1K). No output_format. Default 1.08 tokens ($0.040). Optional job_discounts.seedream_45_ref2i.

8.6 POST /api/generate/faceswap

Requires active Pro subscription (unless boss account).

Submit response:

{
  "job_id": "uuid",
  "status": "submitted",
  "token_cost": 1.0,
  "remaining_tokens": 35.2,
  "status_url": "https://funphantom.in/api/faceswap/uuid"
}

Dedicated status: GET /api/faceswap/{id}

8.7 POST /api/encode/image-mask

Helper to encode source + mask for inpainting. Accepts multipart (image, mask files) or JSON (image_base64, mask_base64).

Response:

{
  "success": true,
  "image_base64": "…",
  "mask_base64": "…",
  "image_width": 1024,
  "image_height": 1024,
  "mask_width": 1024,
  "mask_height": 1024,
  "image_mime": "image/jpeg",
  "mask_mime": "image/png"
}

8.8 POST /api/generate/image-inpaint

Submit response:

{
  "success": true,
  "job_id": "uuid",
  "status": "IN_PROGRESS",
  "mode": "inpaint",
  "token_cost": 0.5,
  "status_url": "https://funphantom.in/image-edit/status/uuid"
}

Poll via unified GET /api/job/{id} (type image_edit).

9. Job Status & Management

9.1 GET /api/job/{id}

Aliases: GET /api/job/{id}/status, GET /api/video-audio/job/{id}

Returns database state only — does not poll RunPod. Poll every 5–10 s until COMPLETED or FAILED.

Common fields (all types):

type: video (in progress)

{
  "job_id": "uuid",
  "type": "video",
  "status": "IN_PROGRESS",
  "progress": 45,
  "created_at": "2026-09-01T12:00:00",
  "started_at": "2026-09-01T12:00:05",
  "completed_at": null,
  "error_message": null,
  "token_cost": 1.2,
  "prompt": "a woman smiling…",
  "lora_template": "blink_missionary",
  "sub_template": null,
  "orientation": "portrait",
  "width": 512,
  "height": 832,
  "result_type": "url"
}

type: video (completed)

{
  "job_id": "uuid",
  "type": "video",
  "status": "COMPLETED",
  "progress": 100,
  "token_cost": 1.2,
  "video_url": "https://funphantom.in/video/uuid",
  "result_urls": ["https://funphantom.in/video/uuid"]
}

If result_type was base64, completed responses may also include video_base64 or video_base64_error.

type: video_audio

Adds mode: "T2V" or "I2V". Completed jobs include video_url, result_urls, and often video_base64.

type: minimax_h3

{
  "job_id": "uuid",
  "type": "minimax_h3",
  "status": "COMPLETED",
  "mode": "t2v",
  "duration": 5,
  "megapixels": 0.4,
  "aspect_ratio": "16:9 (Widescreen)",
  "pre_token_cost": 6.0,
  "token_cost": 5.8,
  "execution_time_ms": 142000,
  "billing_adjusted": true,
  "video_url": "https://funphantom.in/minimax-h3/uuid",
  "result_urls": ["https://funphantom.in/minimax-h3/uuid"],
  "video_base64": "data:video/mp4;base64,…"
}

type: image

Adds model_id, guidance, seed, width, height. Completed: image_url, image_base64.

type: image_edit

Completed: image_url, image_base64 (or image_base64_error if file not ready).

type: faceswap

Adds seed, steps, auto_caption. Completed: image_url, image_base64.

9.2 GET /api/minimax-h3-jobs/{id}

Returns the H3 job's to_dict() plus pre_token_cost, billing_adjusted, and video_url when complete.

9.2b GET /api/wan3-ref2v-jobs/{id}

Aliases: GET /api/wan3-ref2v/job/{id}

Completed jobs include video_url (API-key stream at /api/wan3-ref2v/{id}/video) and video_base64 for partner rehosting.

9.3 GET /api/faceswap/{id}

{
  "job_id": "uuid",
  "status": "COMPLETED",
  "token_cost": 1.0,
  "seed": 123456789,
  "steps": 20,
  "auto_caption": false,
  "error_message": null,
  "created_at": "2026-09-01T12:00:00",
  "completed_at": "2026-09-01T12:02:30",
  "image_url": "https://funphantom.in/faceswap/uuid/image",
  "image_base64": "data:image/jpeg;base64,…"
}

9.4 GET /api/jobs

List jobs across types. Query: page (default 1), per_page (default 20, max 100), status.

Note: Standard users see video, video_audio, and image_edit jobs only. minimax_h3 and faceswap jobs are queryable via unified /api/job/{id} but may not appear in this list.

Response:

{
  "jobs": [
    {
      "id": "uuid",
      "type": "video",
      "status": "COMPLETED",
      "created_at": "2026-09-01T12:00:00",
      "token_cost": 1.2,
      "video_url": "https://funphantom.in/video/uuid"
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 3,
    "per_page": 20,
    "total": 45,
    "has_next": true,
    "has_prev": false
  }
}

Non-boss users receive a sanitized field set (id, type, status, timestamps, token_cost, video_url, image_url, mode, etc.).

9.5 GET /api/stats

{
  "total_jobs": 120,
  "completed_jobs": 98,
  "failed_jobs": 5,
  "pending_jobs": 17,
  "success_rate": 81.67,
  "tokens_remaining": 42.5,
  "subscription_active": true,
  "breakdown": {
    "video": { "total": 80, "completed": 70, "failed": 3, "pending": 7 },
    "video_audio": { "total": 40, "completed": 28, "failed": 2, "pending": 10 }
  }
}

9.6 GET /api/jobs/{id}/settings

Returns reusable settings for a WAN video job (video jobs only).

{
  "success": true,
  "settings": {
    "prompt": "custom prompt if no template",
    "lora_template": "blink_missionary",
    "sub_template": null,
    "duration": 6,
    "auto_upscale": false
  }
}

10. Delete Endpoints

All require X-API-Key. Returns { "success": true, "message": "…" } on success.

11. Catalog & Domain Notes

• API generation does not filter prompts — partners can integrate without domain-specific UX.
• Template catalog: On funphantom.in, curated filtering applies to GET /templates and GET /image-edit-templates.
• Web UI may apply its own filters separately from the API.
• For the complete catalog, use nsfw.funphantom.in.

12. Code Examples

Full video generation flow

import time, requests

API_KEY = "fp_…"
BASE = "https://funphantom.in/api"
H = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Submit
with open("photo.jpg", "rb") as f:
    import base64
    b64 = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()

r = requests.post(f"{BASE}/generate/video", headers=H, json={
    "image_base64": b64,
    "lora_template": "blink_missionary",
    "duration": 6,
    "orientation": "portrait"
})
job_id = r.json()["job_id"]

# Poll
while True:
    s = requests.get(f"{BASE}/job/{job_id}", headers=H).json()
    if s["status"] in ("COMPLETED", "FAILED"):
        print(s)
        break
    time.sleep(8)

13. FAQ

Does the API use HMAC signing? No. Only X-API-Key is required.

Does status polling call RunPod? No. GET /api/job/{id} reads the database. A background worker updates job state.

Are Flow pipeline or standalone upscale available via API? No — those are web-session features only. There are no public API-key endpoints for them.

Does this host filter prompts on generate? No — the API accepts them. Only the template catalog is curated on this host.