Phaya Media API

Phaya is a FastAPI backend that brokers AI media generation across KIE.ai (Sora 2, Veo 3.1, Seedance, Kling, Seedream, Suno), Google Gemini TTS, and OpenRouter LLMs.

Auth

All endpoints require a Bearer token or API key:

Authorization: Bearer <your_api_key>

Set these environment variables before using this skill:

export PHAYA_API_KEY="your_api_key_here"   # required — all endpoints
export PHAYA_BASE="https://your-api-host/api/v1"  # required — your Phaya instance URL

Get your profile and credit balance:

• GET /api/v1/user/profile — full profile
• GET /api/v1/user/credits → { "credits_balance": 84.90, ... }

Rate limit: 60 requests/minute per API key.

Cost Warning

This skill calls a paid credit system. Every generation deducts real credits from your account. Video generation can cost 8–50 credits per job. Start with cheap endpoints (text-to-image at 1 credit) to verify connectivity before running expensive jobs. Credits are auto-refunded on failure, but not on successful jobs you don't use.

Recommendation: create a scoped API key with a small credit balance for initial testing.

Credit System

Every generation costs credits deducted on job creation; auto-refunded on failure.

Job / Polling Pattern

Every generation is async. Create endpoints return job_id immediately; poll the status endpoint.

POST /api/v1/<service>/create   →  { "job_id": "uuid" }
GET  /api/v1/<service>/status/{job_id}  →  { "status": "...", "<media>_url": "..." }

Status values:

• Image/music endpoints: PENDING, QUEUED, PROCESSING, COMPLETED, FAILED
• Speech/subtitle endpoints: PENDING, PROCESSING, COMPLETED, FAILED
• Video/download endpoints: processing, completed, failed, cancelled

Response URL field by media type:

Poll every 3–5 seconds until the terminal status is reached.

Quick Start

1. Generate an image (text-to-image)

import httpx, time

BASE = "https://your-api-host/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

r = httpx.post(f"{BASE}/text-to-image/generate", headers=HEADERS, json={
    "prompt": "A futuristic city at sunset, ultra-detailed",
    "aspect_ratio": "16:9"
})
job_id = r.json()["job_id"]

while True:
    s = httpx.get(f"{BASE}/text-to-image/status/{job_id}", headers=HEADERS).json()
    if s["status"] == "COMPLETED":
        print("Image URL:", s["image_url"])
        break
    if s["status"] == "FAILED":
        raise RuntimeError("Job failed")
    time.sleep(4)

2. Generate a video (Sora 2 text-to-video)

r = httpx.post(f"{BASE}/sora2-text-to-video/create", headers=HEADERS, json={
    "prompt": "A dragon flying over mountains at dawn",
    "aspect_ratio": "landscape",
    "n_frames": "10"          # "10" or "15" as a string
})
job_id = r.json()["job_id"]
# Poll /sora2-text-to-video/status/{job_id} → s["video_url"]

3. Chat with Phaya-GPT

r = httpx.post(f"{BASE}/phaya-gpt/chat/completions", headers=HEADERS, json={
    "messages": [{"role": "user", "content": "Hello, what can you do?"}],
    "stream": False
})
print(r.json()["message"]["content"])   # flat dict — NOT choices[0].message.content

Additional Resources

• Full endpoint reference: endpoints.md
• Curl & Python examples for every category: examples.md

Local Binary Requirements

Most features only need python3 (or curl) and your API key — all AI processing is remote.

Two optional features invoke local binaries on your machine:

• POST /image-to-video/create (FFmpeg local) — requires ffmpeg installed locally
• POST /video-download/create (yt-dlp) — the download runs server-side via yt-dlp on the Phaya host, not locally

No local AI models, GPU, or disk-intensive operations are required by this skill.