Img-Video — Asset Generation Bridge (Multi-Provider)
Claude cannot generate pixels directly, but it can call external model services. This skill encapsulates that pipeline into a single script:
Provide a prompt → Get an image/video → Save to assets/ → Print the relative path, ready for use in HTML, PPT, Markdown, or design files.
The model layer is pluggable: by default it routes through Interface AI (jiekou.ai) relay, and if a key is missing or a call fails, it automatically falls back to providers like
Jimeng / Kling / Gemini, etc. See the full list in references/providers.md.
When to Use
Use this skill whenever your final deliverable should contain an image or a video and a placeholder or plain text is not appropriate. Typical scenarios:
- Web pages / landing pages / email templates: Banners, hero images, illustrations, icon backgrounds
- PPT / slides: Covers, section pages, content images
- Graphic design: Posters, covers, social media cards, thumbnails
- UI prototypes: Diagrams, product screenshot placeholders
- Short videos: Dynamic backgrounds, product showcases, animations driven by a single image
Principle in one sentence: Never leave a blank or write "(insert image here)" — just generate it.
Prerequisites: Configuration
Before first use, prepare a config.json in the skill root directory (the script will error with instructions if it doesn't exist):
- Copy the template:
cp config.example.json config.json - Configure at least one provider — API keys must be obtained from the user, never fabricated. For each provider, set:
type: Provider type (see table below)base_url: API endpoint (has defaults, can be omitted)- Credentials: Usually
api_key; for Kling, useaccess_key+secret_key image_model/video_model: Model name (leavenullif not needed)
- Set
default_provider(primary) andfallback(fallback chain, an array).
Keys are stored only in the local config.json (ignored by .gitignore). Do not include them in code, SKILL.md, or commit them to version control.
Before each session, check availability (confirm keys/capabilities are ready, see the attempt order):
python <skill>/scripts/generate.py providers
Usage
Run this in your project working directory so that the output assets/ relative paths can be directly referenced by web pages or PPT.
Text-to-Image
python <skill>/scripts/generate.py image \
--prompt "Flat illustration style tech company homepage hero image, blue-purple gradient, clean white space" \
--size 1024x1024 --n 1 --output-dir assets/images
| Parameter | Required | Default | Description |
|---|---|---|---|
--prompt | ✅ | — | Be specific (style + subject + color + composition) for best results |
--size | 1024x1024 | Some relays scale proportionally, converting to 1:1 internally | |
--n | 1 | Number of images to generate | |
--output-dir | assets/images | Output directory | |
--provider | Follows fallback chain | Force a specific provider, skipping fallback |
Image-to-Video
python <skill>/scripts/generate.py video \
--image assets/images/xxxx.png \
--prompt "Camera slowly pushes in, background light spots gently floating" --output-dir assets/videos
| Parameter | Required | Default | Description |
|---|---|---|---|
--image | ✅ | — | Local path or http(s) URL |
--prompt | Empty | Motion/scene description; recommended | |
--output-dir | assets/videos | Output directory | |
--provider | Follows fallback chain | Force a specific provider |
Image-to-video tasks are mostly asynchronous; the script automatically polls until completion.
Specify / Switch Providers
- Without
--provider, it automatically triesdefault_provider → fallbackin order (skipping providers without keys or without the required capability). - With
--provider <name>(e.g.,kling/ark/gemini/relay), force a specific provider, skipping the fallback chain. Example: if the user says "use Kling" →--provider kling.
Supported Model Services
type | Service | Text-to-Image | Image-to-Video |
|---|---|---|---|
jiekou | Interface AI Relay (aggregates Midjourney/Flux/Seedance/Kling/Sora/Veo, default) | ✅ | ✅ |
ark / jimeng | ByteDance Jimeng Seedream/Seedance (direct) | ✅ | ✅ |
kling | Kuaishou Kling (direct) | ✅ | ✅ |
gemini | Google Imagen/Veo (direct) | ✅ | ✅ |
relay | Other OpenAI-compatible relay | ✅ | ⚠️ Depends on gateway |
Recommended combinations (jiekou): Text-to-image: mj-txt2img (Midjourney, generates 4 at once), flux-2-pro;
Image-to-video: veo-3.1-generate-img2video (Veo 3.1, with native audio), sora-2-img2video, seedance-v1-pro-i2v.
⚠️ Model switch important: Different models have different prompt field names, duration/resolution enums, and required fields (e.g., Midjourney uses
text, Veo usesduration_seconds+generate_audio). Changing only the model name without adjusting these fields will result in a 400 error. The config already provides switches (prompt_field/send_aspect_ratio/duration/resolution/video_extra), refer to the "Model Field Differences" quick reference inreferences/providers.md.
Output
- Images are saved to
assets/images/, videos toassets/videos/. - Naming:
{timestamp}_{first_words_of_prompt}.{png|jpg|mp4|…}(identifies actual format from file header, automatically avoids overwriting). - The script prints a list of relative paths to the generated files — ready for use in
<img src="assets/images/…">, PPT placeholders, or Markdown.
Typical Workflow
- Use the
providerssubcommand to confirm available services and the attempt order. - Plan which images/videos your final deliverable needs, their purpose, and style.
- Generate each
image(orimagethenvideo) one by one, using--providerwhen you need a specific service. - Collect the printed relative paths and incorporate them into your deliverable.
Example: User says "Help me build a coffee brand landing page"
→ image --prompt "Warm tone pour-over coffee close-up, morning light, shallow depth of field" to generate hero
→ Generate two more product images → Use those assets/images/*.png to write the HTML.
Exceptions and Fallback (Built into Script)
- Missing config.json / missing providers section: Error with instructions to configure.
- Primary provider missing keys / unsupported model: Automatically skips to the next.
- Runtime failure (4xx/5xx/timeout): 5xx and network errors retry with exponential backoff; if still failing, degrades to the next provider in the fallback chain; reports an error only if all providers fail, with a summary of failure reasons from each.
- Video timeout: Exceeds
poll_timeout, reports a clear timeout. - Input image not found (image-to-video): Direct error, check
--image.
Dependencies & Extensibility
- Dependencies: Python 3 +
requests(pip install requests). Kling JWT authentication uses the standard library, no extra dependencies. - Adding new providers: Add a new
Providersubclass inscripts/providers.py, implementinggenerate_image/generate_video, then register it in theREGISTRY— fallback, saving, naming, etc., require no changes. See the end ofreferences/providers.mdfor details.