Phosor AI

Generate AI videos and images (text-to-video, image-to-video, speech-to-video, animate, text-to-image, image-to-image), bring your own LoRA models, and generate AI product/model photography for e-commerce (Image Studio) via the Phosor AI platform.

For detailed API endpoints, parameters, pricing, and limits, see references/api.md.

Setup

Set your API key:

export PHOSOR_API_KEY="your-api-key-here"

Get an API key at phosor.ai → Settings → API Keys.

The CLI script is at scripts/phosor_client.py. All commands output JSON to stdout.

Base URL

The client talks to https://phosor.ai by default, over HTTPS. Get your key from phosor.ai → Settings → API Keys.

python3 scripts/phosor_client.py --api-key <your-key> check-key

To point the same client at another Phosor endpoint, pass --base-url <url> (or set PHOSOR_BASE_URL). HTTPS is required; plain http:// is accepted only for localhost, or when you explicitly add --allow-http.

Note: studio-analyze / studio-suite --image-url must be the full https S3 URL returned by upload-image, not the bare S3 key path — a bare key errors with unsupported URL scheme.

Quick Start

MiniMax H3 — Text-to-Video

H3 is duration-based, not frame-based: it ignores --num-frames / --fps (output is always 24fps) and bills per output second. Pick the frame size with --resolution-tier + --aspect instead of --width/--height.

python3 scripts/phosor_client.py submit "A cat walking on a beach at sunset" \
  --model minimax/h3/text-to-video \
  --resolution-tier 768p --aspect 16:9 --duration 5

MiniMax H3 — Image-to-Video

# Upload first (direct URLs are not accepted); then submit with the returned s3_key
python3 scripts/phosor_client.py upload-image /path/to/first-frame.jpg

python3 scripts/phosor_client.py submit "The person starts dancing" \
  --model minimax/h3/image-to-video \
  --image-url "images/img-xxx.jpg" \
  --end-image-url "images/img-yyy.jpg" \
  --resolution-tier 480p --aspect 9:16 --duration 6

--end-image-url is optional and pins the closing frame.

MiniMax H3 — Reference-to-Video (Ref2VA)

Feed reference images, videos, and audio together; refer to them positionally in the prompt as <Picture 1>, <Picture 2>, … At least one of --reference-image-urls / --reference-video-urls is required.

python3 scripts/phosor_client.py submit \
  "Use <Picture 1> and <Picture 2> as sequential keyframes; slow push-in, cinematic 35mm look." \
  --model minimax/h3/reference-to-video \
  --reference-image-urls "images/a.jpg,images/b.jpg" \
  --reference-audio-urls "audio/voice.mp3" \
  --resolution-tier 768p --aspect 16:9 --duration 5

Reference inputs are billed on top of the output — see Ref2VA Pricing below, and Ref2VA Reference Limits for the caps (the same at 480p and 768p).

Text-to-Video (Wan)

Wan is frame-based. Add /turbo to the model id for the fast, ~3x cheaper variant (it ignores --steps / --guidance).

# Submit T2V job (480p, 81 frames, 16fps)
python3 scripts/phosor_client.py submit "A cat walking on a beach at sunset" \
  --width 854 --height 480 --num-frames 81 --fps 16

# Check status
python3 scripts/phosor_client.py status <request_id>

# Get result (video URL)
python3 scripts/phosor_client.py result <request_id>

Image-to-Video

Two-step flow: upload image first, then submit with the returned S3 key.

# Step 1: Upload image
python3 scripts/phosor_client.py upload-image /path/to/photo.jpg
# Returns: {"file_id": "img-xxx", "s3_key": "images/img-xxx.jpg", ...}

# Step 2: Submit I2V job using the s3_key as image_url
python3 scripts/phosor_client.py submit "The person in the photo starts dancing" \
  --image-url "images/img-xxx.jpg" --width 854 --height 480

Text-to-Image

# Submit T2I job (1024x1024, default settings)
python3 scripts/phosor_client.py submit "A futuristic city skyline at dusk" \
  --model qwen-image/v2512/text-to-image --width 1024 --height 1024

# Generate multiple images at once (1-4)
python3 scripts/phosor_client.py submit "A futuristic city skyline at dusk" \
  --model z-image/turbo/text-to-image --width 1024 --height 768 --num-images 4

# Check status and get result (image URL)
python3 scripts/phosor_client.py status <request_id>
python3 scripts/phosor_client.py result <request_id>
# Returns: {"data": {"image": {"url": "..."}, "seed": 12345}, ...}

Image-to-Image

Two-step flow: upload source image first, then submit with the returned S3 key.

# Step 1: Upload source image
python3 scripts/phosor_client.py upload-image /path/to/photo.jpg
# Returns: {"file_id": "img-xxx", "s3_key": "images/img-xxx.jpg", ...}

# Step 2: Submit I2I job using the s3_key as image_url
python3 scripts/phosor_client.py submit "Transform into oil painting style" \
  --model z-image/turbo/image-to-image --image-url "images/img-xxx.jpg" \
  --width 1024 --height 1024 --strength 0.7

Image Edit (Multi-image Reference)

Two-step flow: upload reference images first, then submit with S3 keys as image_urls.

# Step 1: Upload reference images (up to 3)
python3 scripts/phosor_client.py upload-image /path/to/ref1.jpg
python3 scripts/phosor_client.py upload-image /path/to/ref2.jpg

# Step 2: Submit image-edit job
python3 scripts/phosor_client.py submit \
  "The girl in image 1 is wearing the outfit from image 2" \
  --model qwen-image/v2511/image-edit \
  --image-urls '["images/img-ref1.jpg","images/img-ref2.jpg"]' \
  --width 1024 --height 1024

# Turbo variant (faster, Lightning LoRA built-in)
python3 scripts/phosor_client.py submit \
  "The girl in image 1 is wearing the outfit from image 2" \
  --model qwen-image/v2511/image-edit \
  --image-urls '["images/img-ref1.jpg","images/img-ref2.jpg"]'

Speech-to-Video (S2V)

Two-step flow: upload both audio and reference image first, then submit with the returned S3 keys.

# Step 1: Upload reference image
python3 scripts/phosor_client.py upload-image /path/to/face.jpg
# Returns: {"file_id": "img-xxx", "s3_key": "images/img-xxx.jpg", ...}

# Step 2: Submit S2V job using the s3_key as image_url and audio URL as audio_url
python3 scripts/phosor_client.py submit "A person speaking naturally" \
  --model wan/v2.2-a14b/speech-to-video \
  --image-url "images/img-xxx.jpg" --audio-url "https://example.com/speech.wav" \
  --width 854 --height 480

Animate

Two-step flow: upload both source video and reference image first, then submit.

# Step 1: Upload reference image
python3 scripts/phosor_client.py upload-image /path/to/character.jpg
# Returns: {"file_id": "img-xxx", "s3_key": "images/img-xxx.jpg", ...}

# Step 2: Submit Animate job using the s3_key as image_url and video URL as video_url
python3 scripts/phosor_client.py submit "The character performs the dance moves" \
  --model wan/v2.2-a14b/animate \
  --image-url "images/img-xxx.jpg" --video-url "https://example.com/dance.mp4" \
  --width 854 --height 480

Text-to-Image (GPT Image 2)

Its own resolution set and always exactly 1 image (--num-images is ignored).

python3 scripts/phosor_client.py submit "A ceramic mug on a linen cloth, soft window light" \
  --model openai/gpt-image-2/text-to-image --width 1024 --height 1024

Allowed sizes: 1024×1024 only. Any other size is rejected with 400 Invalid parameters. It ignores --num-images, --steps and --guidance — the only parameters it accepts are prompt, model, width, height and seed.

Text-to-Image (FLUX.2-dev)

FLUX.2-dev has its own resolution whitelist and is fixed at 1 image per request (--num-images and --steps are ignored).

python3 scripts/phosor_client.py submit "Editorial product photo, soft window light" \
  --model flux2/dev/text-to-image --width 2048 --height 1536

Image Edit (FLUX.2-dev)

python3 scripts/phosor_client.py upload-image /path/to/source.jpg

python3 scripts/phosor_client.py submit "Replace the background with a marble surface" \
  --model flux2/dev/image-edit --image-url "images/img-xxx.jpg" \
  --width 1024 --height 1024

Text-to-Speech

TTS takes text (not a prompt) and is billed per character with a minimum charge.

python3 scripts/phosor_client.py submit-tts "Hello, welcome to Phosor AI." \
  --speaker Sohee --language English

LoRA Upload (Custom Pre-trained)

Video LoRA requires two .safetensors files (high_noise + low_noise). Image LoRA requires a single .safetensors file.

# Video LoRA: upload two .safetensors files
python3 scripts/phosor_client.py upload-lora high_noise.safetensors low_noise.safetensors --name "My Style"

# Image LoRA: import single .safetensors file via URL
python3 scripts/phosor_client.py import-lora \
  "https://example.com/my_lora.safetensors" \
  --name "My Image Style"

# Video LoRA: import two files via URL
python3 scripts/phosor_client.py import-lora \
  "https://example.com/high_noise.safetensors" \
  "https://example.com/low_noise.safetensors" \
  --name "My Video Style"

# Check status, then use
python3 scripts/phosor_client.py lora-status <lora_id>
python3 scripts/phosor_client.py submit "A person walking" --lora-id <lora_id>

CLI Commands

Image Studio (Product & Model Photography)

Image Studio is a separate product surface for e-commerce sellers — AI product photography and model/clothing photography — reached through the same gateway and API key as video/LoRA, under the /api/v1/image-studio prefix. It has its own async namespace - the same key name request_id, but a separate id space: an Image Studio request_id is not valid on /api/v1/inference/status/... and vice versa - and its own pricing (flat per-image rate + freemium analyze quota, not per-frame). Full endpoint/parameter reference: references/api.md.

Quick Start: Product Suite

# 1. Upload the product photo
python3 scripts/phosor_client.py upload-image /path/to/product.jpg
# Returns: {"file_id": "img-xxx", "s3_key": "images/img-xxx.jpg", ...}

# 2. (Optional) AI-analyze it first for richer generation context
python3 scripts/phosor_client.py studio-analyze --target product --image-url "images/img-xxx.jpg"

# 3. Generate a product image suite
python3 scripts/phosor_client.py studio-suite --image-url "images/img-xxx.jpg" \
  --layout-types "white_background,lifestyle_scene" --count-per-type 2

# 4. Poll for the result
python3 scripts/phosor_client.py studio-status <request_id>

Quick Start: Clothing/Model Suite

python3 scripts/phosor_client.py upload-image /path/to/garment.jpg
python3 scripts/phosor_client.py studio-clothing-suite \
  --image-urls "images/img-xxx.jpg" \
  --main-image-types '{"model_shot":2,"selling_point":1}' \
  --aplus-types '{"standard_aplus":1}'
python3 scripts/phosor_client.py studio-status <request_id>

Quick Start: One-off Edits (remove-bg, inpaint, translate, etc.)

The long tail of single-purpose editing endpoints doesn't get a dedicated subcommand — use studio-call with the exact field names from references/api.md:

python3 scripts/phosor_client.py studio-call POST /product/remove-bg \
  --json '{"image_url": "images/img-xxx.jpg", "count": 2}'
python3 scripts/phosor_client.py studio-status <request_id>

Key facts

• Every Image Studio call requires X-API-Key (PHOSOR_API_KEY), including GET /pricing — there is no unauthenticated endpoint under this prefix.
• All generation/analyze endpoints are async: POST returns {"request_id": "...", "status": "pending"}; poll studio-status <request_id> until status is "done", "error" or "cancelled". Earlier revisions of this skill said the key was job_id - it is not, and reading it yields undefined. Image Studio ids live in a separate id space from video/LoRA: poll/status/result will not accept an Image Studio request_id.
• Cancelling: POST /jobs/{request_id}/cancel stops a running generation. Images still queued are refunded; images already generating are charged and cannot be stopped; images already delivered bill once through the normal path. The response reports the split as refunded_queued, charged_running and already_done, and the task then polls as status: "cancelled" - not an error.
• Pricing is per-image, not per-frame: call studio-pricing for the live rate. Partial success (e.g. 3 of 5 images) bills only the successes.
• Analyze is freemium: agent/analyze, product/analyze, model/analyze share a daily free quota before per-call billing kicks in.
• model_attrs matters for model-photography endpoints (real-model-swap, mannequin-swap, ai-outfit, ai-wearable) — pass {gender, age_group, ethnicity, skin_tone, hair_color} explicitly; it is not reliably inferred from the source image alone.
• Run studio-features for the full offline endpoint/field catalog without leaving the terminal.

Key Constraints

Video Resolutions (exact pairs only)

Standard (non-turbo) mode: 1080p is capped at 81 frames due to generation time limits.

S2V / Animate Video Resolutions (exact pairs only)

Image Resolutions (exact pairs only)

MiniMax H3 Frame Sizes (--resolution-tier + --aspect)

duration is 4–15 seconds (default 5). Output FPS is fixed at 24 and frames_per_second is ignored.

Ref2VA Reference Limits (minimax/h3/reference-to-video)

Caps differ per tier, and the image cap is higher when you send only images:

FLUX.2-dev Resolutions (exact pairs only)

FLUX.2-dev does not accept the general image resolution list above, and always returns exactly 1 image.

Frame Alignment (video only)

Frames must follow 1 + 4*k where k >= 1 (e.g. 5, 9, 13, ... 81, 85, ...). Server auto-aligns down.

Video Inference Parameters

Image Inference Parameters

Concurrency

Model API inference jobs run concurrently up to a per-account cap; over it the submit returns 429 and you retry after a job finishes.

Image Studio runs on its own pool and does not consume this quota — a suite and a video generation can run at the same time.

Multiple LoRAs

python3 scripts/phosor_client.py submit "A person dancing" \
  --loras '[{"lora_id": "lora-abc", "lora_scale": 0.8}, {"lora_id": "lora-def", "lora_scale": 0.5}]'

Two-Step Upload Rule

Files must be uploaded before use — direct URLs are NOT supported in submit --image-url:

1. Image → upload-image / import-image → returns s3_key → use as --image-url
2. LoRA → upload-lora / import-lora → returns lora_id → use as --lora-id

Queue Flow

PENDING → PROCESSING → COMPLETED / FAILED

The poll command checks all locally-tracked pending jobs and removes completed/failed ones.

MiniMax H3 Pricing (per output second)

Per output second, regardless of clip length:

Ref2VA inputs

Output plus reference inputs:

total = duration x base_rate
      + max(0, reference_images - 5) x image_rate   # first 5 images free
      + reference_video_seconds x base_rate         # reference audio is free

Example — reference-to-video, 5s at 768p with 4 reference images: 5 x $0.012 = 0.6 credits. 5s at 480p with 9 images: 5 x $0.0045 + 4 x $0.0075 = 0.525 credits.

Wan Video Pricing (per frame)

LoRA multiplier on turbo: 1.2x.

S2V Pricing (per frame)

Animate Pricing (per frame)

Image Pricing (per image)

Flat per image at every resolution. Multiply by num_images (1–4) where the model supports it; FLUX.2-dev is fixed at 1 image per request.

Audio Pricing

Exchange rate: 10 credits = $1 USD. Credits pre-deducted, auto-refunded on failure. Live rates: GET /api/v1/pricing/config — always prefer it over any table here.