Jogg API

Use this skill when the task is about JoggAI v2 endpoint execution or one of the main multi-step API workflows.

All paths in this document are relative to the current skill root directory.

Runner:

• bash "scripts/jogg-v2.sh"

Do not use this skill for lip sync. Use jogg-lip-sync instead.

Trigger

• User wants to call a JoggAI v2 endpoint directly
• User asks to generate avatar videos, product videos, template videos, scripts, photo avatars, or product avatars
• User asks to translate a video
• User wants to upload local media and reuse the returned asset_url
• User wants webhook setup, event listing, endpoint updates, or quota/account lookups
• User already has an async ID and wants the current result without writing integration code

Hard Rules

• Use scripts/jogg-v2.sh as the execution entrypoint
• Prefer --workflow for scenario requests and --op for direct endpoint requests
• Do not write ad hoc curl commands when the runtime already supports the operation
• Do not poll list endpoints
• Poll only status endpoints for async tasks
• Poll no faster than every 10 seconds
• Always keep polling bounded by both max_wait_seconds and max_poll_attempts
• If the latest state is still non-terminal after the limit, return the last payload and stop
• If the user only wants status, use workflow get-result or the specific *-get operation

Required Inputs

• JOGG_API_KEY is required
• JOGG_BASE_URL is optional and defaults to https://api.jogg.ai
• JOGG_API_PLATFORM is optional and defaults to openclaw

Polling defaults:

• JOGG_API_DEFAULT_POLL_INTERVAL_SECONDS=15
• JOGG_API_DEFAULT_MAX_WAIT_SECONDS=1800
• JOGG_API_DEFAULT_MAX_POLL_ATTEMPTS=90

Intent Routing

• “查某个接口 / 调 voices / 看模板列表 / 查用户额度” Use --op
• “帮我做商品视频 / 做数字人口播 / 创建照片数字人 / 建 webhook / 翻译视频” Use --workflow
• “我已经有 task_id/video_id/batch_id，帮我查结果” Use --workflow get-result

Endpoint Mode

List supported endpoint operations:

bash "scripts/jogg-v2.sh" --list-ops

Generic pattern:

bash "scripts/jogg-v2.sh" \
  --op "<operation>" \
  --body-json '<json>' \
  --query-json '<json>' \
  --path-json '<json>'

Examples:

bash "scripts/jogg-v2.sh" \
  --op "voices-list" \
  --query-json '{"language":"en-US","gender":"Male"}'

bash "scripts/jogg-v2.sh" \
  --op "avatar-video-get" \
  --path-json '{"id":"video_123456"}' \
  --poll

For the full endpoint catalog, see references/endpoints.md.

Workflow Mode

List supported workflows:

bash "scripts/jogg-v2.sh" --list-workflows

Generic pattern:

bash "scripts/jogg-v2.sh" \
  --workflow "<workflow>" \
  --body-json '<json>' \
  --poll

Supported workflows:

• upload-media
• ai-scripts
• create-photo-avatar
• photo-avatar-motion
• avatar-video
• avatar-video-with-photo-avatar
• avatar-video-with-custom-audio
• avatar-video-transparent
• url-to-video
• create-template-video
• video-translation
• product-avatar
• webhook-integration
• get-result

For the flow definitions and step order, see references/workflows.md.

Workflow Inputs

upload-media

• required: file_path
• optional: content_type

ai-scripts

• same payload as POST /v2/ai_scripts
• returns either submit result or final script payload

create-photo-avatar

• same payload as POST /v2/photo_avatar/photo/generate
• optional convenience field: image_path

photo-avatar-motion

• required: name, voice_id, model
• one of:
  • image_url
  • photo_id

avatar-video

• same payload as POST /v2/create_video_from_avatar
• optional convenience field: voice.audio_path

url-to-video

• product: create-product payload
• product_update: optional update-product payload without product_id
• render_mode: direct or preview
• create_request: required in direct mode
• preview_request: required in preview mode
• preview_index: optional, defaults to 0

create-template-video

• same payload as POST /v2/create_video_with_template
• optional convenience field: variables[].properties.local_path

video-translation

• same payload as POST /v2/video_translate/
• optional convenience field: video_path

product-avatar

• generation: payload for POST /v2/product_avatar/generation
• motion: payload for POST /v2/product_avatar/add_motion without generation_id
• optional convenience field: product_image_path

webhook-integration

• action: list, events, create, update, or delete
• create: payload for POST /v2/endpoint
• update: payload for PUT /v2/endpoint/{endpoint_id} plus endpoint_id
• delete: needs endpoint_id

get-result

• required: kind
• plus the corresponding async identifier

Output Contract

• stdout returns machine-readable JSON only
• stderr is reserved for progress logs
• create workflows return submit info plus the final result when polling is enabled
• timed-out polls return the last known payload with poll_timeout: true

Examples

Create AI scripts:

bash "scripts/jogg-v2.sh" \
  --workflow "ai-scripts" \
  --body-json '{
    "language":"english",
    "video_length_seconds":"30",
    "script_style":"Storytime",
    "product_info":{
      "source_type":"details",
      "data":{
        "name":"Amazing Smart Bottle",
        "description":"Self-cleaning bottle for travel and fitness use"
      }
    }
  }'

Create photo avatar and stop after submit:

bash "scripts/jogg-v2.sh" \
  --workflow "create-photo-avatar" \
  --body-json '{
    "age":"Adult",
    "avatar_style":"Professional",
    "gender":"Female",
    "model":"modern",
    "aspect_ratio":"portrait",
    "image_path":"/tmp/portrait.jpg"
  }' \
  --no-poll

Create product video through preview flow:

bash "scripts/jogg-v2.sh" \
  --workflow "url-to-video" \
  --body-json '{
    "product":{
      "url":"https://example.com/product-page"
    },
    "render_mode":"preview",
    "preview_request":{
      "visual_styles":["Simple Product Switch","Dynamic Showcase"],
      "video_spec":{"aspect_ratio":"landscape","length":"30","caption":true},
      "avatar":{"id":1,"type":0},
      "voice":{"id":"en-US-ChristopherNeural"},
      "audio":{"music_id":13},
      "script":{"style":"Storytime","language":"english"}
    }
  }'