Code examples

Set VIGGLE_API_KEY before using these examples. Replace all sample IDs with the complete IDs returned by your account.

Credits — `GET /v1/credits`

req, _ := http.NewRequest("GET", "https://apis.viggle.ai/v1/credits", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); resp, _ := http.DefaultClient.Do(req)

const resp = await fetch("https://apis.viggle.ai/v1/credits", {headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}});

resp = requests.get("https://apis.viggle.ai/v1/credits", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"})

curl "https://apis.viggle.ai/v1/credits" -H "Authorization: Bearer $VIGGLE_API_KEY"

Create Character — `POST /v1/characters`

body := &bytes.Buffer{}; w := multipart.NewWriter(body); f, _ := w.CreateFormFile("image", "character.png"); file, _ := os.Open("character.png"); io.Copy(f, file); w.WriteField("name", "Presenter"); w.Close()
req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/characters", body); req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); req.Header.Set("Content-Type", w.FormDataContentType()); resp, _ := http.DefaultClient.Do(req)

const form = new FormData(); form.append("image", imageFile); form.append("name", "Presenter");
const resp = await fetch("https://apis.viggle.ai/v1/characters", {method:"POST", headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}, body:form});

with open("character.png", "rb") as image:
    resp = requests.post("https://apis.viggle.ai/v1/characters", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}, files={"image": image}, data={"name": "Presenter"})

curl -X POST "https://apis.viggle.ai/v1/characters" -H "Authorization: Bearer $VIGGLE_API_KEY" -F "[email protected]" -F "name=Presenter"

Add -F "type=vsplat" to also extract a 3D vsplat (all keeps the render too):

cURL

curl -X POST "https://apis.viggle.ai/v1/characters" -H "Authorization: Bearer $VIGGLE_API_KEY" -F "[email protected]" -F "type=vsplat"

List, get, delete, and export Characters

req, _ := http.NewRequest("GET", "https://apis.viggle.ai/v1/characters/char_550e8400-e29b-41d4-a716-446655440000", nil); req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); resp, _ := http.DefaultClient.Do(req)

const resp = await fetch(`https://apis.viggle.ai/v1/characters/${characterId}`, {headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}});

resp = requests.get(f"https://apis.viggle.ai/v1/characters/{character_id}", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"})

curl "https://apis.viggle.ai/v1/characters" -H "Authorization: Bearer $VIGGLE_API_KEY"
curl "https://apis.viggle.ai/v1/characters/char_550e8400-e29b-41d4-a716-446655440000" -H "Authorization: Bearer $VIGGLE_API_KEY"
curl -X DELETE "https://apis.viggle.ai/v1/characters/char_550e8400-e29b-41d4-a716-446655440000" -H "Authorization: Bearer $VIGGLE_API_KEY"
curl "https://apis.viggle.ai/v1/characters/char_550e8400-e29b-41d4-a716-446655440000/export?download_type=vsplat" -H "Authorization: Bearer $VIGGLE_API_KEY"

For list, use GET /v1/characters; for deletion, change the request method to DELETE. See Characters for every request and response field.

Create Motion (from Video) — `POST /v1/motions`

body := &bytes.Buffer{}; w := multipart.NewWriter(body); f, _ := w.CreateFormFile("motion_video", "dance.mp4"); file, _ := os.Open("dance.mp4"); io.Copy(f, file); w.WriteField("name", "Dance"); w.Close()
req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/motions", body); req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); req.Header.Set("Content-Type", w.FormDataContentType()); resp, _ := http.DefaultClient.Do(req)

const form = new FormData(); form.append("motion_video", videoFile); form.append("name", "Dance");
const resp = await fetch("https://apis.viggle.ai/v1/motions", {method:"POST", headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}, body:form});

with open("dance.mp4", "rb") as video:
    resp = requests.post("https://apis.viggle.ai/v1/motions", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}, files={"motion_video": video}, data={"name": "Dance"})

curl -X POST "https://apis.viggle.ai/v1/motions" -H "Authorization: Bearer $VIGGLE_API_KEY" -F "[email protected]" -F "name=Dance"

Add -F "type=glb" to also extract a 3D animation.

Create Motion (from Text) — `POST /v1/motions`

The endpoint is the same, but text-to-motion uses application/json instead of multipart form data.

const resp = await fetch("https://apis.viggle.ai/v1/motions", {method:"POST", headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`, "Content-Type":"application/json"}, body:JSON.stringify({text:"a person doing a cartwheel", duration_seconds:5})});

resp = requests.post("https://apis.viggle.ai/v1/motions", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}, json={"text":"a person doing a cartwheel", "duration_seconds":5})

curl -X POST "https://apis.viggle.ai/v1/motions" -H "Authorization: Bearer $VIGGLE_API_KEY" -H "Content-Type: application/json" -d '{"text":"a person doing a cartwheel","duration_seconds":5}'

Import Motion — `POST /v1/motions/import`

body := strings.NewReader(`{"template_id":"YOUR_TEMPLATE_ID","name":"Campaign dance"}`); req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/motions/import", body); req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); req.Header.Set("Content-Type", "application/json"); resp, _ := http.DefaultClient.Do(req)

const resp = await fetch("https://apis.viggle.ai/v1/motions/import", {method:"POST", headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`, "Content-Type":"application/json"}, body:JSON.stringify({template_id:"YOUR_TEMPLATE_ID", name:"Campaign dance"})});

resp = requests.post("https://apis.viggle.ai/v1/motions/import", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}, json={"template_id":"YOUR_TEMPLATE_ID", "name":"Campaign dance"})

curl -X POST "https://apis.viggle.ai/v1/motions/import" -H "Authorization: Bearer $VIGGLE_API_KEY" -H "Content-Type: application/json" -d '{"template_id":"YOUR_TEMPLATE_ID","name":"Campaign dance"}'

List, get, delete, and export Motions

req, _ := http.NewRequest("GET", "https://apis.viggle.ai/v1/motions/mot_550e8400-e29b-41d4-a716-446655440000", nil); req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); resp, _ := http.DefaultClient.Do(req)

const resp = await fetch(`https://apis.viggle.ai/v1/motions/${motionId}`, {headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}});

resp = requests.get(f"https://apis.viggle.ai/v1/motions/{motion_id}", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"})

curl "https://apis.viggle.ai/v1/motions" -H "Authorization: Bearer $VIGGLE_API_KEY"
curl "https://apis.viggle.ai/v1/motions/mot_550e8400-e29b-41d4-a716-446655440000" -H "Authorization: Bearer $VIGGLE_API_KEY"
curl -X DELETE "https://apis.viggle.ai/v1/motions/mot_550e8400-e29b-41d4-a716-446655440000" -H "Authorization: Bearer $VIGGLE_API_KEY"
curl "https://apis.viggle.ai/v1/motions/mot_550e8400-e29b-41d4-a716-446655440000/export?download_type=mixamo" -H "Authorization: Bearer $VIGGLE_API_KEY"

Create, list, get, and download a Render

body := &bytes.Buffer{}; w := multipart.NewWriter(body); w.WriteField("character_id", "char_550e8400-e29b-41d4-a716-446655440000"); w.WriteField("motion_id", "mot_550e8400-e29b-41d4-a716-446655440000"); w.Close()
req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/renders", body); req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); req.Header.Set("Content-Type", w.FormDataContentType()); resp, _ := http.DefaultClient.Do(req)

const form = new FormData(); form.append("character_id", characterId); form.append("motion_id", motionId);
const resp = await fetch("https://apis.viggle.ai/v1/renders", {method:"POST", headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}, body:form});

resp = requests.post("https://apis.viggle.ai/v1/renders", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}, data={"character_id": character_id, "motion_id": motion_id})

curl -X POST "https://apis.viggle.ai/v1/renders" -H "Authorization: Bearer $VIGGLE_API_KEY" -F "character_id=char_550e8400-e29b-41d4-a716-446655440000" -F "motion_id=mot_550e8400-e29b-41d4-a716-446655440000"
curl "https://apis.viggle.ai/v1/videos?status=ready&limit=20" -H "Authorization: Bearer $VIGGLE_API_KEY"
curl "https://apis.viggle.ai/v1/videos/render_8f50b2c2c2b84ae0" -H "Authorization: Bearer $VIGGLE_API_KEY"
curl -L "https://apis.viggle.ai/v1/renders/render_8f50b2c2c2b84ae0/download" -H "Authorization: Bearer $VIGGLE_API_KEY" -o output.mp4

Listing and status checks go through GET /v1/videos / GET /v1/videos/{video_id} — see List Videos and Get Video. The equivalent GET /v1/renders and GET /v1/renders/{render_id} are retired (405). There is no cancel endpoint. See Renders for parameter combinations and response fields.

Create a Render from a prepared draft

curl -X POST "https://apis.viggle.ai/v1/renders/prepare" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"character":{"kind":"asset","asset_id":"char_550e8400-e29b-41d4-a716-446655440000"},"motion":{"kind":"asset","asset_id":"mot_550e8400-e29b-41d4-a716-446655440000"}}'

curl -X POST "https://apis.viggle.ai/v1/renders" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"draft_id":"draft_abc123"}'

import os, uuid, requests

headers = {"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}
draft = requests.post(
    "https://apis.viggle.ai/v1/renders/prepare",
    headers=headers,
    json={
        "character": {"kind": "asset", "asset_id": "char_550e8400-e29b-41d4-a716-446655440000"},
        "motion": {"kind": "asset", "asset_id": "mot_550e8400-e29b-41d4-a716-446655440000"},
    },
).json()

render = requests.post(
    "https://apis.viggle.ai/v1/renders",
    headers={**headers, "Idempotency-Key": str(uuid.uuid4())},
    json={"draft_id": draft["draft_id"]},
)
render.raise_for_status()

When either source is kind: "upload", PUT the bytes to each uploads[].url from the prepare response before calling POST /v1/renders. See Prepare Render for the full flow.

Watch a Render over Server-Sent Events

curl -N "https://apis.viggle.ai/v1/renders/render_8f50b2c2c2b84ae0/events" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "Accept: text/event-stream"

See Watch Render for the event vocabulary and reconnect semantics.

Generate a Video — `POST /v1/videos`

Text-to-video, first-frame-to-video, and first+last-frame-to-video all share this endpoint — which mode runs depends on which frame fields you send.

curl "https://apis.viggle.ai/v1/videos" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F prompt="a paper airplane gliding through a sunlit office" \
  -F quality=low \
  -F duration_s=5

curl "https://apis.viggle.ai/v1/videos" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F prompt="camera slowly zooms out" \
  -F quality=high \
  -F first_frame_image_url=https://example.test/first.png

curl "https://apis.viggle.ai/v1/videos" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F prompt="camera pans across the room" \
  -F quality=low \
  -F first_frame_image_url=https://example.test/first.png \
  -F last_frame_image_url=https://example.test/last.png

import os, requests
resp = requests.post(
    "https://apis.viggle.ai/v1/videos",
    headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
    data={"prompt": "camera slowly zooms out", "quality": "high"},
    files={"first_frame_image": open("first.png", "rb")},
)
resp.raise_for_status()
video = resp.json()

All three modes answer 200 with the same {id, status, progress, created_at} acceptance shape. See Generate Video (from Text), Generate Video (from First Frame and/or Text), and Generate Video (from First-Last Frames and/or Text) for the full field reference and common validation errors.

Endpoint-by-endpoint request examples

The following compact examples show the exact HTTP method, path, and request shape for every endpoint. In the Go snippets, client is an http.Client; in JavaScript, apiKey is your API key; in Python, headers is {"Authorization": "Bearer ..."}.

`GET /v1/characters`

req, _ := http.NewRequest("GET", base+"/characters", nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/characters`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/characters", headers=headers)

curl "$BASE/characters" -H "Authorization: Bearer $VIGGLE_API_KEY"

`GET /v1/characters/{character_id}`

req, _ := http.NewRequest("GET", base+"/characters/"+characterID, nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/characters/${characterId}`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/characters/{character_id}", headers=headers)

curl "$BASE/characters/$CHARACTER_ID" -H "Authorization: Bearer $VIGGLE_API_KEY"

`DELETE /v1/characters/{character_id}`

req, _ := http.NewRequest("DELETE", base+"/characters/"+characterID, nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/characters/${characterId}`, {method:"DELETE", headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.delete(f"{base}/characters/{character_id}", headers=headers)

curl -X DELETE "$BASE/characters/$CHARACTER_ID" -H "Authorization: Bearer $VIGGLE_API_KEY"

`GET /v1/characters/{character_id}/export`

req, _ := http.NewRequest("GET", base+"/characters/"+characterID+"/export?download_type=vsplat", nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/characters/${characterId}/export?download_type=vsplat`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/characters/{character_id}/export", params={"download_type": "vsplat"}, headers=headers)

curl "$BASE/characters/$CHARACTER_ID/export?download_type=vsplat" -H "Authorization: Bearer $VIGGLE_API_KEY"

`GET /v1/motions`

req, _ := http.NewRequest("GET", base+"/motions", nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/motions`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/motions", headers=headers)

curl "$BASE/motions" -H "Authorization: Bearer $VIGGLE_API_KEY"

`GET /v1/motions/{motion_id}`

req, _ := http.NewRequest("GET", base+"/motions/"+motionID, nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/motions/${motionId}`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/motions/{motion_id}", headers=headers)

curl "$BASE/motions/$MOTION_ID" -H "Authorization: Bearer $VIGGLE_API_KEY"

`DELETE /v1/motions/{motion_id}`

req, _ := http.NewRequest("DELETE", base+"/motions/"+motionID, nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/motions/${motionId}`, {method:"DELETE", headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.delete(f"{base}/motions/{motion_id}", headers=headers)

curl -X DELETE "$BASE/motions/$MOTION_ID" -H "Authorization: Bearer $VIGGLE_API_KEY"

`GET /v1/motions/{motion_id}/export`

req, _ := http.NewRequest("GET", base+"/motions/"+motionID+"/export?download_type=mixamo", nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/motions/${motionId}/export?download_type=mixamo`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/motions/{motion_id}/export", params={"download_type": "mixamo"}, headers=headers)

curl "$BASE/motions/$MOTION_ID/export?download_type=mixamo" -H "Authorization: Bearer $VIGGLE_API_KEY"

`GET /v1/videos`

Replaces the retired GET /v1/renders (now 405 Method Not Allowed). Lists Renders and H3 text-to-video generations merged into one feed.

req, _ := http.NewRequest("GET", base+"/videos?status=ready&limit=20", nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/videos?status=ready&limit=20`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/videos", params={"status": "ready", "limit": 20}, headers=headers)

curl "$BASE/videos?status=ready&limit=20" -H "Authorization: Bearer $VIGGLE_API_KEY"

`GET /v1/videos/{video_id}`

Replaces the retired GET /v1/renders/{render_id} (now 405 Method Not Allowed). Accepts a render_ or vid_ prefixed ID.

req, _ := http.NewRequest("GET", base+"/videos/"+videoID, nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/videos/${videoId}`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/videos/{video_id}", headers=headers)

curl "$BASE/videos/$VIDEO_ID" -H "Authorization: Bearer $VIGGLE_API_KEY"

`GET /v1/renders/{render_id}/events`

req, _ := http.NewRequest("GET", base+"/renders/"+renderID+"/events", nil); req.Header.Set("Authorization", "Bearer "+apiKey); req.Header.Set("Accept", "text/event-stream"); resp, _ := client.Do(req)

curl -N "$BASE/renders/$RENDER_ID/events" -H "Authorization: Bearer $VIGGLE_API_KEY" -H "Accept: text/event-stream"

`GET /v1/renders/{render_id}/download`

req, _ := http.NewRequest("GET", base+"/renders/"+renderID+"/download", nil); req.Header.Set("Authorization", "Bearer "+apiKey); resp, _ := client.Do(req)

const resp = await fetch(`${base}/renders/${renderId}/download`, {headers:{Authorization:`Bearer ${apiKey}`}});

resp = requests.get(f"{base}/renders/{render_id}/download", headers=headers, allow_redirects=True)

curl -L "$BASE/renders/$RENDER_ID/download" -H "Authorization: Bearer $VIGGLE_API_KEY" -o output.mp4

Get Started

Guides

Production

Credits — `GET /v1/credits`

Create Character — `POST /v1/characters`

List, get, delete, and export Characters

Create Motion (from Video) — `POST /v1/motions`

Create Motion (from Text) — `POST /v1/motions`

Import Motion — `POST /v1/motions/import`

List, get, delete, and export Motions

Create, list, get, and download a Render

Create a Render from a prepared draft

Watch a Render over Server-Sent Events

Generate a Video — `POST /v1/videos`

Endpoint-by-endpoint request examples

`GET /v1/characters`

`GET /v1/characters/{character_id}`

`DELETE /v1/characters/{character_id}`

`GET /v1/characters/{character_id}/export`

`GET /v1/motions`

`GET /v1/motions/{motion_id}`

`DELETE /v1/motions/{motion_id}`

`GET /v1/motions/{motion_id}/export`

`GET /v1/videos`

`GET /v1/videos/{video_id}`

`GET /v1/renders/{render_id}/events`

`GET /v1/renders/{render_id}/download`

​Credits — GET /v1/credits

​Create Character — POST /v1/characters

​List, get, delete, and export Characters

​Create Motion (from Video) — POST /v1/motions

​Create Motion (from Text) — POST /v1/motions

​Import Motion — POST /v1/motions/import

​List, get, delete, and export Motions

​Create, list, get, and download a Render

​Create a Render from a prepared draft

​Watch a Render over Server-Sent Events

​Generate a Video — POST /v1/videos

​Endpoint-by-endpoint request examples

​GET /v1/characters

​GET /v1/characters/{character_id}

​DELETE /v1/characters/{character_id}

​GET /v1/characters/{character_id}/export

​GET /v1/motions

​GET /v1/motions/{motion_id}

​DELETE /v1/motions/{motion_id}

​GET /v1/motions/{motion_id}/export

​GET /v1/videos

​GET /v1/videos/{video_id}

​GET /v1/renders/{render_id}/events

​GET /v1/renders/{render_id}/download

Credits — `GET /v1/credits`

Create Character — `POST /v1/characters`

List, get, delete, and export Characters

Create Motion (from Video) — `POST /v1/motions`

Create Motion (from Text) — `POST /v1/motions`

Import Motion — `POST /v1/motions/import`

List, get, delete, and export Motions

Create, list, get, and download a Render

Create a Render from a prepared draft

Watch a Render over Server-Sent Events

Generate a Video — `POST /v1/videos`

Endpoint-by-endpoint request examples

`GET /v1/characters`

`GET /v1/characters/{character_id}`

`DELETE /v1/characters/{character_id}`

`GET /v1/characters/{character_id}/export`

`GET /v1/motions`

`GET /v1/motions/{motion_id}`

`DELETE /v1/motions/{motion_id}`

`GET /v1/motions/{motion_id}/export`

`GET /v1/videos`

`GET /v1/videos/{video_id}`

`GET /v1/renders/{render_id}/events`

`GET /v1/renders/{render_id}/download`