Vivago AI Skill#

Integration with Vivago AI (智小象) platform for AI-powered image and video generation.

Supported Features#

Image Generation#

• Text to Image ( txt2img): Generate images from text descriptions
• Image to Image ( img2img): Transform existing images based on prompts, including style transfer, image editing, and multi-image fusion

Video Generation#

• Text to Video ( txt2vid): Generate videos from text descriptions
• Image to Video ( img2vid): Generate videos from static images
• Keyframe to Video ( keyframe_to_video): Generate transition videos from start and end keyframes
• Video Templates ( template_to_video): 181 pre-defined video effects
• Supports multiple model versions (v3Pro, v3L, kling-video-o1)

Additional Features#

• Image upload to Vivago storage
• Batch generation (up to 4 images)
• Multiple aspect ratios (1:1, 4:3, 3:4, 16:9, 9:16)
• Automatic retry with polling

Architecture#

Core Modules#

text

scripts/
├── vivago_client.py       # Main API client
├── template_manager.py    # Template management
├── config_loader.py       # Configuration loading
├── enums.py              # Type enums (TaskStatus, AspectRatio, etc.)
├── exceptions.py         # Structured exceptions
└── config/               # Modular configuration files

Code Quality#

• Type Safety: Complete type annotations and enums
• Exception Handling: Structured exception hierarchy
• CI/CD: GitHub Actions for automated testing
• Modular Config: Split configuration files for maintainability

Setup#

Prerequisites#

Before using this skill, you need to obtain a Vivago.ai API Token:

Step 1: Login to Vivago.ai

1. Visit https://vivago.ai/ and log in to your account
2. Check your remaining credits and consider subscribing to a suitable plan if needed

Step 2: Obtain Your Token

1. After logging in, visit https://vivago.ai/prod-api/user/token
2. The page will return your API Token (in JWT format)
3. Copy this Token for configuration

Security Note: The Token is your credential for accessing the API. Please keep it secure and do not share it with others.

Environment Variables#

Security Note: For secure deployments and AI Agents, the system requires the token to be passed strictly via the HIDREAM_AUTHORIZATION environment variable.

Export it securely in your current session:

bash

export HIDREAM_AUTHORIZATION="your_vivago_api_token"

Note: STORAGE_AK and STORAGE_SK are deprecated and removed. The image upload uses secure pre-signed URLs provided by the Vivago API.

File Output Configuration#

Important: By default, all generated resources (JSON results, downloaded images, and videos) will be output to the assets/ directory within the current working folder. Ensure this directory exists or the system has permission to create it.

Installation#

bash

pip install -r requirements.txt

Usage#

Python API#

python

from scripts import create_client, VivagoClient
from scripts.enums import AspectRatio, PortName, TaskStatus
from scripts.exceptions import TaskFailedError, TaskTimeoutError

# Create client
client = create_client()

# Text to image
results = client.text_to_image(
    prompt="a beautiful sunset over mountains",
    port=PortName.KLING_IMAGE,  # or PortName.NANO_BANANA
    wh_ratio=AspectRatio.RATIO_16_9,
    batch_size=2
)

# Image to video (using local image)
results = client.image_to_video(
    prompt="camera slowly zooming out",
    image_uuid=client.upload_image("/path/to/image.jpg"),
    port=PortName.V3PRO,
    wh_ratio=AspectRatio.RATIO_16_9,
    duration=5
)

# Keyframe to video (using start and end images)
results = client.keyframe_to_video(
    prompt="smooth transition from start to end",
    start_image_uuid=client.upload_image("/path/to/start.jpg"),
    end_image_uuid=client.upload_image("/path/to/end.jpg"),
    port=PortName.V3PRO,
    wh_ratio=AspectRatio.RATIO_16_9,
    duration=5
)

# Video Templates - use pre-defined effects
results = client.template_to_video(
    image_uuid=client.upload_image("/path/to/image.jpg"),
    template="ghibli",  # See available templates below
    wh_ratio=AspectRatio.RATIO_9_16
)

Error Handling#

python

from scripts.exceptions import (
    TaskFailedError,
    TaskRejectedError,
    TaskTimeoutError,
    InvalidPortError
)

try:
    results = client.image_to_video(...)
except TaskFailedError as e:
    print(f"Task failed: {e.task_id}")
except TaskRejectedError as e:
    print(f"Content rejected: {e.reason}")
except TaskTimeoutError as e:
    print(f"Timeout after {e.timeout_seconds}s")
except InvalidPortError as e:
    print(f"Invalid port: {e.port}, available: {e.available}")

Command Line (Best for AI Agents)#

For AI Agents: The easiest way to use this skill is through the provided CLI scripts. They automatically handle API communication, polling, and result parsing. By default, they use HiDream's native models.

Text to Image:

bash

python3 scripts/txt2img.py \
  --prompt "a futuristic city" \
  --wh-ratio 16:9 \
  --batch-size 2 \
  --output ./assets/results.json

Note: This defaults to the hidream-txt2img model.

Text to Video:

bash

python3 scripts/txt2vid.py \
  --prompt "a cybernetic dragon flying over a futuristic city" \
  --wh-ratio 16:9 \
  --duration 5 \
  --output ./assets/video_results.json

Note: This defaults to the v3Pro model.

Image to Video:

bash

python3 scripts/img2video.py \
  --prompt "slow motion falling leaves" \
  --image ./assets/source_image.jpg \
  --duration 5 \
  --output ./assets/video.json

API Reference#

Enums#

python

from scripts.enums import (
    TaskStatus,      # PENDING, COMPLETED, PROCESSING, FAILED, REJECTED
    AspectRatio,     # RATIO_1_1, RATIO_4_3, RATIO_16_9, etc.
    PortCategory,    # TEXT_TO_IMAGE, IMAGE_TO_VIDEO, etc.
    PortName         # KLING_IMAGE, V3PRO, NANO_BANANA, etc.
)

Models#

FeatureAvailable VersionsDefaultText to Imagev3L (HiDream), kling-image-o1v3L (via port hidream-txt2img)Image to Videov3Pro, v3L, kling-video-o1v3ProKeyframe to Videov3Pro, v3Lv3Pro

Note for AI Agents: By default, all CLI tools ( txt2img.py, txt2vid.py) are pre-configured to use HiDream's native models ( hidream-txt2img for images, v3Pro for videos). You don't need to specify the model unless explicitly requested by the user.

Aspect Ratios#

• 1:1 - Square
• 4:3 - Standard
• 3:4 - Portrait
• 16:9 - Widescreen
• 9:16 - Mobile/Vertical

Task Status Codes#

python

from scripts.enums import TaskStatus

TaskStatus.PENDING     # 0 - Pending
TaskStatus.COMPLETED   # 1 - Completed
TaskStatus.PROCESSING  # 2 - Processing
TaskStatus.FAILED      # 3 - Failed
TaskStatus.REJECTED    # 4 - Rejected (content review)

File Structure#

text

vivago-ai-skill/
├── scripts/
│   ├── __init__.py         # Package exports
│   ├── vivago_client.py    # Core API client
│   ├── template_manager.py # Template management
│   ├── config_loader.py    # Configuration loader
│   ├── enums.py            # Type enums
│   ├── exceptions.py       # Exception classes
│   ├── logging_config.py   # Logging configuration
│   └── config/             # Modular config files
│       ├── base.json
│       ├── text_to_image.json
│       ├── image_to_video.json
│       └── ...
├── tests/
│   ├── conftest.py         # Pytest configuration
│   ├── archive/            # Archived tests
│   └── ...
├── docs/                   # Documentation
├── .github/workflows/      # CI configuration
├── requirements.txt
├── README.md
└── SKILL.md               # This file

Important Notes#

Feishu Channel Messaging Guidelines#

When sending generated content through Feishu (飞书) channel:

Content TypeSend MethodExampleImages✅ Direct file uploadAttach image file directlyVideos❌ Must send as linkhttps://media.vivago.ai/{video_uuid}

⚠️ Critical: Videos CANNOT be sent as file attachments in Feishu. Always construct and send the direct media URL:

text

https://media.vivago.ai/b1268f08-ac32-4b83-863f-a419797d768e.mp4

Why: Feishu does not support playable video attachments. Sending video files directly will result in delivery failure or unplayable content.

Image Download#

Images can be downloaded using the correct URL format:

text

https://storage.vivago.ai/image/{image_name}.jpg

Example:

python

from scripts import create_client
import requests

client = create_client()

# Generate image
results = client.text_to_image(prompt="a cute cat")
image_name = results[0].get('image', '')

# Download image
image_url = f"https://storage.vivago.ai/image/{image_name}.jpg"
response = requests.get(image_url)
with open("output.jpg", "wb") as f:
    f.write(response.content)

Sending via Feishu:

python

# Download and send through Feishu
image_data = requests.get(image_url).content
# Then send image_data as file attachment via Feishu API

Asynchronous Processing#

• API calls are asynchronous with automatic polling
• Images are automatically resized to max 1024px on longest side before upload
• Video generation supports 5 or 10 second durations
• Batch size for images: 1-4, for videos: 1
• All API calls include automatic retry logic

Error Handling#

The client handles common errors:

• Network timeouts (with retry)
• Rate limiting (with exponential backoff)
• Invalid parameters (validation before API call)
• Task failures (structured exceptions)

Exception Hierarchy#

text

VivagoError (base)
├── VivagoAPIError
├── MissingCredentialError
├── InvalidPortError
├── ImageUploadError
├── TemplateNotFoundError
└── TaskError
    ├── TaskFailedError
    ├── TaskRejectedError
    └── TaskTimeoutError

Video Templates Reference#

The following 181 video templates are available via template_to_video():

Quick Categories#

CategoryCountExample TemplatesStyle Transfer20+ghibli, 1930s-2000s vintage stylesHarry Potter4magic_reveal_ravenclaw, gryffindor, hufflepuff, slytherinWings/Fantasy10+angel_wings, phoenix_wings, crystal_wings, fire_wingsSuperheroes5+iron_man, cat_woman, ghost_riderDance10+apt, dadada, dance, limbo_danceEffects15+ash_out, metallic_liquid, flash_floodThanksgiving10+turkey_chasing, autumn_feast, gratitude_photoComics/Cartoon8+gta_star, anime_figure, bring_comics_to_lifeProducts8+glasses_display, music_box, food_product_displayScenes20+romantic_kiss, graduation, starship_chef

Popular Templates#

Template IDDescriptionghibli / ghibli2Studio Ghibli animation stylemagic_reveal_ravenclawHarry Potter Ravenclaw transformationmagic_reveal_gryffindorHarry Potter Gryffindor transformationmagic_reveal_hufflepuffHarry Potter Hufflepuff transformationmagic_reveal_slytherinHarry Potter Slytherin transformationiron_manIron Man armor assemblyangel_wings / phoenix_wings / crystal_wings / fire_wingsWing transformationscat_womanCat Woman styleghost_riderGhost Rider flaming skulljokerJoker villain stylemermaidMermaid underwater scenesnow_whiteSnow White princessbarbieBarbie princess transformationme_in_handMiniature figure in handmusic_boxRotating figure on music boxanime_figureTransform into anime figuregta_starGTA game style transformationapt / dadada / danceDance templatesash_outDisintegrate into asheseye_of_the_stormThunder god awakeningmetallic_liquidMetal mask transformationflash_floodWater/flood effectturkey_chasing / turkey_away / turkey_giantThanksgiving turkey scenesautumn_feast / autumn_strollAutumn scenesrenovation_of_old_photosColorize B&W photosgraduationGraduation ceremonyglasses / glasses_displayGlasses/eyewear showcasebikini / sexy_man / sexy_pantsFashion/beachromantic_kiss / boyfriends_rose / girlfriends_roseRomantic scenesai_archaeologist / starship_chef / cyber_cookerSci-fi charactersjungle_reign / panther_queen / roar_of_the_dustlands / tiger_snuggleAnimal companionsinstant_sadness / headphone_vibe / relaxEmotion/reactionfrost_alertCold/freeze effectbald_meBald transformationboom_hair / curl_pop / long_hairHair transformationsmusclesMuscle transformationface_punch / gun_pointAction effectsstatic_shot / tracking_shot / orbit_shot / push_in / zoom_out / handheld_shotCamera movementsearth_zoom_in / earth_zoom_outEarth zoom effects

View All Templates#

python

from scripts.template_manager import get_template_manager

manager = get_template_manager()
templates = manager.list_templates()

print(f"Total templates: {len(templates)}")
for tid, name in sorted(templates.items()):
    print(f"  {tid}: {name}")

Usage Example#

python

from scripts import create_client

client = create_client()

# Upload image
image_uuid = client.upload_image("/path/to/photo.jpg")

# Apply Ghibli style template
results = client.template_to_video(
    image_uuid=image_uuid,
    template="ghibli",
    wh_ratio="9:16"
)

# Harry Potter transformation
results = client.template_to_video(
    image_uuid=image_uuid,
    template="magic_reveal_ravenclaw",
    wh_ratio="9:16"
)

Changelog#

v0.9.0 (2026-03-09)#

• ✅ Code review complete (P0-P3)
• ✅ Added GitHub Actions CI
• ✅ Added type safety module (enums.py)
• ✅ Added structured exceptions (exceptions.py)
• ✅ Split configuration into modular files
• ✅ Archived redundant code and tests
• ✅ Pinned dependency versions

v0.8.2 (2026-03-08)#

• ✅ Template testing: 44 templates, 40 passed (90.9%)
• ✅ Fixed metallic_liquid naming issue
• ✅ Marked long_hair as deprecated

v0.8.0 (2026-03-07)#

• ✅ Completed Tier 1-4 testing
• ✅ Established smart test optimization system