DreamAPI Skill

25 AI tools powered by DreamAPI , from Newport AI.

intent

this skill wraps 25 DreamAPI tools across avatars, image generation, image editing, video generation, video editing, video translation, and voice cloning. use it whenever a user needs to generate or edit images, videos, or audio synthetically. the skill auto-handles polling, file uploads, and auth flow. expect 30 seconds to 5 minutes per task depending on type.

inputs

required environment

• DREAMAPI_API_KEY: your DreamAPI account API key from https://api.newportai.com/. get it by signing in with google or github and copying from the dashboard.

python runtime

• python 3.8 or higher
• install dependencies: pip install -r {baseDir}/scripts/requirements.txt

external connection: dreamapi

• service: DreamAPI (Newport AI)
• auth method: API key (bearer token)
• endpoints: https://api.newportai.com/ (portal), https://api.dreamapi.ai/ (api)
• setup: env var DREAMAPI_API_KEY must be set before running any script. scripts will check auth status automatically.
• rate limits: per-account credits system. each task consumes credits based on type. check balance with scripts/user.py credit.
• file uploads: local files (images, videos, audio) auto-upload to DreamAPI storage when passed as script arguments. no manual upload needed.

external context (optional)

• task ID from a previous timed-out run (for resume with query)
• reference docs in references/ folder (auth.md, avatar.md, image_gen.md, etc.)

procedure

step 1: authenticate (once per session)

input: none (first run only)

• run python3 scripts/auth.py status to check if API key is already set
• if not set, show user the login message (see decision points below)
• once user provides API key, set env var: export DREAMAPI_API_KEY=<key>
• verify with python3 scripts/auth.py status again

output: authenticated session; DREAMAPI_API_KEY env var loaded

step 2: select tool by user intent (route to correct script)

input: user description of what they want (e.g. "make a talking face from this photo and audio")

• match user request against tool selection guide (see decision points for full tree)
• identify which module (avatar, image_gen, image_edit, video_gen, video_edit, video_translate, voice, user)
• identify which command (e.g. lipsync, text2image, colorize, text2video, etc.)

output: selected script path and command name

step 3: submit task with run (new request)

input: script, command, user parameters (text prompt, file paths, voice settings, etc.)

• assemble command: python3 scripts/{module}.py {command} run [options]
• pass file paths directly (images, videos, audio). scripts auto-detect and upload
• include user parameters (prompt, voice id, quality, language, etc.)
• execute and wait for polling to complete (runs in foreground by default)

output: task ID, status, result URL (if complete within default timeout of 600 seconds)

step 4: handle timeout (if run exceeds 600s)

input: task ID from step 3, user's original request

• if polling times out before completion, save the task ID
• inform user of estimated wait time from table below
• offer to resume with query (step 5) when user is ready

output: task ID for later query; message to user with next steps

step 5: resume with query (timeout recovery)

input: task ID from a previous run, original request context

• run python3 scripts/{module}.py {command} query --task-id <id> --timeout 600
• polls again with fresh timeout window
• if still incomplete after 600s, user can request query again with --timeout 1200

output: updated status; result URL if now complete; error if task failed (status=4)

step 6: handle task failure

input: task status=4 (failed) returned by run or query

• inform user in plain language what went wrong (see error_handling.md for code mapping)
• ask if user wants to retry or adjust parameters
• do not auto-resubmit; wait for explicit user approval

output: error explanation; ready for user decision (retry, adjust, or cancel)

step 7: deliver result

input: completed task (status=3), result URL, metadata (dimensions, duration, voices used, etc.)

• show result URL directly (image, video, or audio link)
• include brief metadata (resolution, duration, model used, etc.)
• use result template: [emoji] [type] complete | Result: [URL] • [metadata]
• ask if user wants adjustments

output: user sees final asset; knows task succeeded

step 8: check credit balance (optional, before/after)

input: none (queries account)

• run python3 scripts/user.py credit at any time
• shows remaining credits and usage summary

output: credit balance; task cost breakdown

decision points

authentication gate

if no DREAMAPI_API_KEY env var set, user must log in first. send this message (exact format):

To get started, you need a DreamAPI API key.

1. Go to: https://api.newportai.com/
2. Sign in with Google or GitHub
3. Copy your API key from the Dashboard

Once you have your key, just tell me and I'll set it up for you.

(Chinese variant available in original doc above.)

else: proceed with authenticated session.

tool routing tree

user request → match against intent below → route to script + command

talking face synced to audio?
  → has video + audio file → avatar.py lipsync run
  → has photo + audio file → avatar.py dreamavatar run
  → wants character to perform actions from driving video → avatar.py dreamact run

generate image from text prompt?
  → image_gen.py text2image run

transform or restyle existing image?
  → image_gen.py image2image run

edit an image (colorize, enhance, fill, replace, remove bg)?
  → image_edit.py colorize run (b&w photo → color)
  → image_edit.py enhance run (boost quality)
  → image_edit.py outpainting run (extend borders)
  → image_edit.py inpainting run (fill/replace region)
  → image_edit.py swap-face run (replace face in image)
  → image_edit.py remove-bg run (strip background)

generate video from text?
  → video_gen.py text2video run

animate a still image into video?
  → video_gen.py image2video run

create smooth transition between two images?
  → video_gen.py head-tail run

edit a video (face swap, matting, composite)?
  → video_edit.py swap-face run (replace face in video)
  → video_edit.py matting run (remove background from video)
  → video_edit.py composite run (replace background in video)

translate video speech?
  → video_translate.py run (en/zh/es)

text-to-speech?
  → voice.py tts-common run (standard quality)
  → voice.py tts-pro run (premium)
  → voice.py clone run + voice.py tts-clone run (custom voice)

list available voices?
  → voice.py list

check credits?
  → user.py credit

outside capability set?
  → tell user clearly not supported yet

polling and timeout recovery

if run completes within 600s (default): → show result immediately, go to step 7

else if run times out (polling exceeds 600s): → save task ID → inform user with estimated wait time from table below → offer to resume with query --task-id <id> when ready

if query also times out after 600s: → user can request query --task-id <id> --timeout 1200 for longer wait → repeat as needed

if task status returns 4 (failed): → ask user to retry or adjust parameters → do not auto-resubmit

file upload routing

if user passes local file path (image, video, audio): → scripts auto-detect and upload to DreamAPI storage → pass file path directly as argument; no manual upload → if upload fails (network timeout, quota), inform user and ask to retry

else if user passes URL: → use URL directly; no upload needed

credits edge case

if user has zero credits remaining: → run will fail with insufficient credits error → direct user to purchase credits via dashboard → do not retry

output contract

task submission (after run)

{
  "taskId": "string (save for query if needed)",
  "status": "integer (0-2=processing, 3=success, 4=failed)",
  "estimatedTime": "string from table below (if processing)"
}

task completion (status=3)

{
  "taskId": "string",
  "status": 3,
  "result": {
    "url": "string (https://... direct link to asset)",
    "metadata": {
      "type": "image|video|audio",
      "dimensions": "WxH (images/videos)",
      "duration": "seconds (video/audio)",
      "model": "string (Flux, Wan2.1, DreamAvatar, etc.)"
    }
  }
}

task failure (status=4)

{
  "taskId": "string",
  "status": 4,
  "error": {
    "code": "integer (see error_handling.md)",
    "message": "string (user-friendly error)"
  }
}

credit balance query

{
  "credits": "integer (remaining)",
  "monthlyUsage": "object (breakdown by task type)"
}

estimated generation times (inform user after submission)

Task Type	Estimated Time
Avatar (LipSync / DreamAvatar / Dreamact)	2 to 5 min
Image Generation (Flux)	30s to 1 min
Image Editing (Colorize / Enhance / etc.)	30s to 1 min
Video Generation (Wan2.1)	3 to 5 min
Video Editing (Swap Face / Matting)	2 to 5 min
Video Translate	3 to 5 min
Voice Clone	30s to 1 min
TTS (Common / Pro / Clone)	10s to 30s
Remove Background	10s to 30s

file output locations

• result URLs are permanent DreamAPI storage links (https://cdn.dreamapi.ai/...)
• user can download, share, or embed directly
• no local file writes unless user explicitly saves

outcome signal

user knows the skill worked when:

1. authentication succeeded: auth.py status returns authenticated: true
2. task submitted: user sees task ID and estimated wait time message
3. task completed: user receives result URL directly, with metadata (dimensions, duration, model)
4. result is usable: result URL is live and downloads/plays correctly (test by opening in browser or sending to user)
5. user confirms: user sees asset and explicitly says "looks good" or requests adjustments
6. credits deducted: balance decreased; user can verify via user.py credit

user-facing reply rules (enforce for every response)

• keep replies short. give result or next step directly, no filler.
• use plain language. no api jargon, no terminal refs, no env var mentions, no polling explanations.
• never mention terminal details. no command output, logs, exit codes, file paths, or config internals in user message.
• always send login link as https://api.newportai.com/ if login needed.
• explain errors in one sentence. ask if user wants to retry.
• be result-oriented. after completion, send result url first, then metadata. skip intermediate steps.
• give time estimates. after submit, tell user the wait time from the table.

result message template

[emoji] [task type] complete

Result: <OUTPUT_URL>
• [key metadata line]

Not happy with the result? Let me know and I'll adjust.

example success outcomes

• user says "make a talking head video" → skill submits, user gets "Avatar complete | Result: [url] | estimated 3-5 min"
• task finishes → skill sends "Avatar complete | Result: [url] • 1280x720 video, 45s, DreamAvatar model"
• user says "enhance this blurry photo" → skill submits and completes in 45s → "Image edit complete | Result: [url] • 2048x1536 PNG, enhanced quality"
• user says "how many credits" → skill returns "You have 450 credits remaining"
• user says "clone my voice" → skill returns "Voice cloned | Clone ID: abc123 | Ready to use in text-to-speech"