VisionARI

External API v2 — Showcase Developer Guide

Programmatically create fully-customized Pro Showcases, upload pictures, and queue them for AR conversion.

Authentication

Every v2 request requires an API key in the X-API-Key header.

Key type	Where to get it	Billing
Per-user key (`vsk_live_…`)	Your account → API Keys	Charges your credit balance + collection slots.
Owner shared key	`VISIONARI_API_KEY` env var	Free. Created content is attributed to the internal `api-service` user.

The owner shared key bypasses billing. Per-user keys are required for any third-party integration so consumption can be attributed and billed correctly.

Pricing (per-user / billable mode)

Operation	Credits
Create showcase	5.0
Per uploaded picture (AR conversion)	2.0

Credits are deducted from the same balance you see in-app — there is no separate "API credits" pool. Track spend in your account → API Usage.

1. Verify your key

curl -H "X-API-Key: vsk_live_..." https://visionarispace.com/api/v2/me

2. Create a Pro Showcase

curl -X POST https://visionarispace.com/api/v2/showcases \
  -H "X-API-Key: vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "logo_url": "https://yourcdn.com/logo.png",
    "layout_choice": "branded",
    "description": "Spring 2026 collection",
    "custom_links": [
      {"title": "Shop", "url": "https://yourstore.com"},
      {"title": "Instagram", "url": "https://instagram.com/you"}
    ],
    "branding": {
      "tagline": "Walk through the collection in AR",
      "primary_color": "#6c63ff",
      "secondary_color": "#ff6c85"
    },
    "image_urls": ["https://yourcdn.com/piece1.jpg", "https://yourcdn.com/piece2.jpg"]
  }'

Response includes the public url, embed_url, and a list of queued_jobs for the initial pictures.

3. Add more pictures (multipart upload OR URLs)

Multipart files

curl -X POST https://visionarispace.com/api/v2/showcases/123/items \
  -H "X-API-Key: vsk_live_..." \
  -F "files=@./painting1.jpg" \
  -F "files=@./painting2.jpg"

By URL

curl -X POST https://visionarispace.com/api/v2/showcases/123/items \
  -H "X-API-Key: vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"image_urls": ["https://yourcdn.com/painting3.jpg"]}'

Each picture is queued for AR conversion at its uploaded pixel size — no forced resize. Physical AR plane dimensions are auto-derived (24″ on the shorter side).

4. Poll job status

curl -H "X-API-Key: vsk_live_..." https://visionarispace.com/api/v2/jobs/v2_abc123...

Status values: queued → downloading → converting → uploading → completed | failed.

5. Retrieve full showcase + items

curl -H "X-API-Key: vsk_live_..." https://visionarispace.com/api/v2/showcases/123

Animated AR (video & background removal)

Turn a still image into a moving AR card (AI-generated motion), or bring your own short video — both bake into an animated USDZ (iOS Quick Look) + GLB (Android Scene Viewer) pair. Optionally cut out the subject for a transparent card with remove_background. This endpoint is async: it returns a job_id you poll on /api/v2/jobs/<job_id>.

Pricing

Request	Credits
Image source (motion + bake)	13.5
Image source + background removal	15.0
Video source (bake only)	1.0
Video source + background removal	2.5

Pricing is computed per request and echoed back in the pricing field of the POST response and the credits_charged total. A failed job is automatically refunded. Owner-key calls are free.

Request parameters

Field	Notes
image_url	Still image to animate. Provide either this or `video_url` (not both). An already-animated image (GIF / APNG / animated WEBP) is baked straight from its own frames — the AI motion step is skipped and not charged, and per-frame transparency is preserved.
video_url	Your own short clip (mp4/mov/webm, ≤200MB) to bake directly into an animated card.
remove_background	Optional bool. Cuts out the subject per-frame for a transparent card.
motion_style	Optional motion preset (image source only). Unknown values fall back to the default.
video_model	Optional image-to-video model identifier (image source only). Must be an enabled model.
width_inches / height_inches	Optional physical AR plane size. Defaults to 24″ on the shorter side.
callback_url	Optional https URL POSTed with the final job payload when the job finishes or fails.

Animate a still image

curl -X POST https://visionarispace.com/api/v2/animated-ar \
  -H "X-API-Key: vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://yourcdn.com/poster.jpg",
    "remove_background": true
  }'

Bake your own video

curl -X POST https://visionarispace.com/api/v2/animated-ar \
  -H "X-API-Key: vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://yourcdn.com/clip.mp4"}'

Source URLs must be publicly reachable https links that resolve directly (no redirects). The job returns usdz_url, glb_url, a preview_url poster, embed_url (+ embed_url_static), and the created ar_model_id / image_id in result.

If you submit an already-animated image (GIF/APNG/animated WEBP), the AI motion step is skipped and that portion of the up-front charge is refunded. The result reports ai_motion_skipped along with the corrected billing — credits_charged (gross), credits_refunded, and net_credits_charged — so you can reconcile against the 202 response without inspecting the credit ledger.

Endpoint Reference

Method	Path	Purpose
GET	/api/v2/me	Identity + balance
POST	/api/v2/showcases	Create Pro showcase
GET	/api/v2/showcases/<id>	Showcase + items
POST	/api/v2/showcases/<id>/items	Upload pictures
GET	/api/v2/showcases/<id>/items/<item_id>	Single item
POST	/api/v2/animated-ar	Animated AR (image/video + bg removal)
GET	/api/v2/jobs/<job_id>	Job status

Existing v1 single-image API

The v1 /api/v1/convert endpoint remains free because the resulting embed carries VisionARI branding. Use v1 when you only need a single image converted with the standard widget; use v2 when you need a fully-customized Pro Showcase with multiple items and your own branding.