Open API Documentation

Integrate PVShow AI generation capabilities into your applications via RESTful API. Supports text-to-image, image-to-image, text-to-video, and image-to-video.

Base URL: https://api.pvshow.net/api/v1/open

Open API

Allow third-party applications to call PVShow generation capabilities via API Key authentication. Supports text-to-image, image-to-image, text-to-video, and image-to-video.

Base URL: https://api.pvshow.net/api/v1/open

Authentication

Open API uses API Key authentication. You can pass the key via either method below (choose one):

Method	Header
X-API-Key	X-API-Key: pvs_xxxx
Bearer Token	Authorization: Bearer pvs_xxxx

Go to Dashboard → API Keys to create and manage your keys

Endpoints

Method	Path	Description
POST	/generations	Create generation task (returns 202)
GET	/generations	List tasks
GET	/generations/{task_id}	Query task status
POST	/generations/{task_id}/cancel	Cancel task
GET	/balance	Query credit balance
GET	/models	List available models

POST /generations — Request Body

Field	Type	Required	Description
type	string	✓	text_to_image / image_to_image / text_to_video / image_to_video
model	string	✓	Model name (e.g. sd2-agent)
prompt	string	✓	Generation prompt
image_url	string	—	Input image URL (required for image_to_image / image_to_video)
image_urls	string[]	—	Multiple input images
callback_url	string	—	Webhook URL for this task; overrides API key default
params	object	—	Model-specific parameters (resolution, duration, ratio…)

Code Examples

python

import httpx

API_KEY = "pvs_your_api_key_here"
BASE = "https://api.pvshow.net/api/v1/open"
HEADERS = {"X-API-Key": API_KEY}

# Text to Image
resp = httpx.post(f"{BASE}/generations", headers=HEADERS, json={
    "type": "text_to_image",
    "model": "sd2-agent",
    "prompt": "a cyberpunk city at night",
    "params": {"resolution_type": "2k"},
})
task = resp.json()
print(f"Task: {task['task_id']}, Cost: {task['cost_credits']}")

# Text to Video
resp = httpx.post(f"{BASE}/generations", headers=HEADERS, json={
    "type": "text_to_video",
    "model": "sd2-agent",
    "prompt": "a rocket launching into space",
    "params": {"duration": 5, "ratio": "16:9"},
})

# Image to Video
resp = httpx.post(f"{BASE}/generations", headers=HEADERS, json={
    "type": "image_to_video",
    "model": "sd2-agent",
    "prompt": "the scene comes alive with wind",
    "image_url": "https://example.com/photo.jpg",
    "callback_url": "https://your-server.com/webhook",
})

# Check balance
balance = httpx.get(f"{BASE}/balance", headers=HEADERS).json()
print(f"Balance: {balance['balance']} credits")

Webhook

When a task completes or fails, PVShow will POST the result to your configured callback URL.

Callback URL Priority

1callback_url provided in the generation request (highest priority)

2Default callback_url configured on the API Key

3Not set — you must poll GET /generations/{task_id}

Event Types

Event	Description
task.completed	Task succeeded — result_url and media_type included
task.failed	Task failed — error_message included, credits auto-refunded

Payload Example

json

{
  "event": "task.completed",
  "task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "text_to_image",
  "model": "sd2-agent",
  "status": "completed",
  "result_url": "https://cdn.pvshow.net/results/xxx/yyy.png",
  "media_type": "image",
  "error_message": null,
  "cost_credits": 15,
  "created_at": "2026-04-05T10:30:00Z",
  "completed_at": "2026-04-05T10:31:00Z"
}

Retry Policy

Failed deliveries are retried up to 5 times with exponential backoff (2s → 4s → 8s → 16s → 32s). Your server should return a 2xx status code to acknowledge receipt.

Receiver Example

python

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook")
async def handle_webhook(request: Request):
    payload = await request.json()

    if payload["event"] == "task.completed":
        result_url = payload["result_url"]
        media_type = payload["media_type"]  # "image" or "video"
        # process the result ...
    elif payload["event"] == "task.failed":
        error = payload["error_message"]
        # credits already refunded automatically

    return {"status": "ok"}

Credits

Type	Parameter	Credits
Text to Image (1k/2k)	resolution_type	15
Text to Image (4k)	resolution_type	20
Text to Video (5s)	duration	200
Text to Video (10s)	duration	400
Text to Video (5s, 1080p)	video_resolution	300
Image to Video	—	Same as text-to-video

Credits are automatically refunded when a task fails or is cancelled.

Models & Status

Response Fields

Field	Type	Description
task_id	string	Task ID
status	string	Task status
result_url	string \| null	Result download URL (available after completion)
error_message	string \| null	Error message (on failure)
cost_credits	number	Credits consumed for this task
created_at	string	Created time (ISO 8601)

TaskStatus

Value	Description
queued	Queued
pending	Pending
processing	Generating
completed	Completed
failed	Failed
cancelled	Cancelled

TaskType

Value	Description
text_to_image	Text to Image
image_to_image	Image to Image
text_to_video	Text to Video
image_to_video	Image to Video