relay-studio-media

name	relay-studio-media
description	Query and invoke a Relay Studio reverse-proxy for AI image and video generation. Use when an agent needs to discover Relay Studio model capabilities; generate, edit, or reference images; run Seedance text-to-video, image-to-video, first/last-frame, or Seedance 2.0 multimodal video generation with reference video/audio URLs; control supported video audio generation; poll tasks; download generated assets; or write prompts for the Seedream/Seedance models exposed by techdou/relay-studio. Prefer this skill over guessing OpenAI, Coze, Seedream, or Seedance request fields because Relay Studio has its own validated API contract and deployment-specific model capabilities.
license	MIT
metadata	{"version":"1.1.1","source_repository":"https://github.com/techdou/relay-studio","audited_branch":"main","audited_commit":"e5d51eeb99b7000b63f8993f561d7c6192795837","audited_at":"2026-08-17","runtime":"Python 3.9+ with network access; no third-party Python packages required"}

Relay Studio Media Skill

Use Relay Studio's reverse-proxy contract instead of calling Coze SDK internals directly.

Source of truth

Treat current route code and /api/v1/models capability output as authoritative for calls. The repository README still contains stale video request examples.

Read only what the task needs:

• API fields, auth, responses, scopes: references/api-contract.md
• Agent operation/model selection: references/agent-routing.md
• Image prompt writing: references/prompt-image.md
• Video/Seedance prompt writing: references/prompt-video.md
• Known upstream mismatches: references/known-gaps.md
• Curl/API examples: references/examples.md
• Source audit map: references/source-map.md
• Skill quality review: references/quality-review.md

Use scripts/relay_media.py for deterministic calls.

Required environment

Prefer environment variables so secrets do not enter shell history:

export RELAY_STUDIO_BASE_URL="https://your-relay-host/api/v1"
export RELAY_STUDIO_API_KEY="irs_live_..."

For a Web/Supabase session instead:

export RELAY_STUDIO_SESSION_TOKEN="..."

Alternatively, copy assets/.env.example to .env in the skill root and fill in real values: the wrapper auto-loads RELAY_STUDIO_* entries from it at startup. Exported environment variables always take precedence over .env values.

Never print keys, session tokens, auth headers, or full base64 media payloads.

Agent workflow

1. Classify the requested operation.

   • model discovery -> models
   • text-to-image -> image-generate
   • image-to-image from existing Relay asset IDs -> image-generate --reference-asset-id ...
   • local image edit/reference composition -> image-edit
   • upload reusable local image -> upload-reference
   • text-to-video -> video-text
   • one local first frame -> video-image
   • first + last local frames -> video-transition
   • existing Relay image asset IDs -> video-assets
   • reference video/audio URL workflow -> video-multimodal
   • task inspection -> task

2. Query models before choosing a model unless the user gave an exact deployed Relay model code.

   python3 scripts/relay_media.py models --type video
   

   API-key model listing now exposes type, text/image-to-video flags, supported resolutions/ratios/durations, reference-video/audio support, and defaults. Prefer these returned capabilities over hard-coded assumptions. It still does not expose supports_multiple_references, so first+last-frame support cannot be proven from API-key /models alone.

3. Choose a model compatible with the requested inputs. Current seed defaults include:

   • image-pro -> Seedream 5.0 family
   • image-standard -> Seedream 4.5 family
   • video-seedance-1.5-pro -> Seedance 1.5 Pro
   • video-seedance-2.0 -> Seedance 2.0 multimodal

   These are seed defaults, not a guarantee about a deployed instance. /models wins.

4. Write prompt text separately from control fields. Put content, appearance, motion, camera, reference mapping, continuity, and audio intent in the prompt. Keep size/resolution/ratio/duration/count/audio toggle in API fields.

5. Use the wrapper script. It emits JSON and validates the public Relay route contract before sending.

Quick commands

List video models/capabilities:

python3 scripts/relay_media.py models --type video

Text to image:

python3 scripts/relay_media.py image-generate \
  --model image-pro \
  --prompt "一只橘猫坐在雨夜咖啡馆窗边，暖色室内灯与蓝色雨夜形成冷暖对比，电影感写实摄影" \
  --size 2K

Local image edit:

python3 scripts/relay_media.py image-edit \
  --model image-pro \
  --image ./source.png \
  --prompt "保留人物身份、姿态和构图，只把服装改为深蓝色羊毛大衣，保持真实摄影质感"

Seedance 1.5 Pro text-to-video with explicit audio:

python3 scripts/relay_media.py video-text \
  --model video-seedance-1.5-pro \
  --prompt "中景跟拍，一只金毛犬沿海边木栈道小跑，海风吹动毛发，夕阳逆光，动作自然连续，电影写实风格；环境声为海浪和海风" \
  --resolution 720p --ratio 16:9 --duration 5 --generate-audio true

Image-to-video:

python3 scripts/relay_media.py video-image \
  --model video-seedance-1.5-pro \
  --image ./first-frame.png \
  --prompt "保持首帧人物外观和场景不变，人物缓慢转头看向镜头并轻轻微笑，镜头缓慢推进" \
  --duration 5

First/last-frame transition:

python3 scripts/relay_media.py video-transition \
  --model video-seedance-2.0 \
  --first-frame ./start.png \
  --last-frame ./end.png \
  --prompt "从首帧自然连续过渡到尾帧，人物向前走两步后坐下，保持身份、服装和场景一致，不切镜" \
  --duration 5

Seedance 2.0 with reference video/audio URLs:

python3 scripts/relay_media.py video-multimodal \
  --model video-seedance-2.0 \
  --prompt "以参考视频的运镜节奏为参考，以参考音频的节拍组织动作，生成同一产品的电影感广告镜头" \
  --reference-video-url "https://cdn.example.com/reference.mp4" \
  --reference-audio-url "https://cdn.example.com/reference.mp3" \
  --resolution 720p --ratio 16:9 --duration 8

Inspect a task:

python3 scripts/relay_media.py task <task-id>

Public route constraints

Images

• /images/generations is synchronous and best for external Agent text-to-image / existing-asset image-to-image.
• n: 1-4 at schema level; model/user limits may be lower.
• response_format: url or b64_json.
• /images/edits is multipart and accepts one source image, up to four extra reference_image files, and optional mask.
• Treat edit mask as compatibility/reference guidance, not guaranteed pixel-accurate inpainting.

Videos

The public /videos route still derives image mode from reference_asset_ids count:

• 0 image asset IDs -> text-to-video
• 1 image asset ID -> image-to-video, role=first_frame
• 2 image asset IDs -> first/last-frame in array order

Route-level controls currently include:

• resolution: 480p | 720p | 1080p
• ratio: 16:9 | 9:16 | 1:1 | 4:3 | 3:4 | 21:9 | adaptive
• duration: -1 or integer 4..12; -1 means model-selected duration
• optional generate_audio
• up to 3 reference_videos URLs
• up to 3 reference_audios URLs
• up to 2 reference_asset_ids image references

Model support is narrower than route enums. Query /models and validate the chosen ratio/duration/reference modality against that model.

Reference video/audio values must be provider-reachable HTTP(S) URLs. The current public API does not provide a working local video/audio upload-to-URL flow; see references/known-gaps.md.

Error handling

• 401: auth/key invalid.
• 403: missing scope, disabled API access, model denial, or ownership denial.
• 400/422: request/model capability mismatch; fix fields rather than retrying blindly.
• quota/concurrency/rate errors: report; retry only if plausibly transient.
• provider/server errors: bounded retry may be appropriate; reuse the same idempotency_key for the same intended generation.

Never silently change model, source media, ratio, duration, audio behavior, or reference ordering merely to make a request pass.

Before finishing

Confirm:

• model type matches the intended media;
• selected model capabilities permit the requested controls/reference modalities;
• prompt and API controls do not conflict;
• first/last image order is correct;
• reference video/audio URLs are provider reachable;
• video reached terminal succeeded before claiming completion;
• final signed asset URL or downloaded path exists;
• any semantic limitation (especially edit mask or upstream upload gaps) is disclosed.