Mediaio Generate

Media.io Generate

Submit image and video jobs through the current mediaio CLI contract. Treat CLI help, model/workflow/effect discovery, and model get/workflow get output as the source of truth.

Step 0 — Bootstrap

Before any generation command:

1. Run command -v mediaio and mediaio version. If the command is missing, tell the user that the shared Media.io CLI must be installed; do not silently install a second runtime from this skill.

   • If mediaio version prints an Update: line ending with (update available), treat that as a required handoff point: quote that line and ask whether to run mediaio upgrade --output json before continuing.

   • The hint is throttled to once every 24 hours, so its absence means "no new hint today", not "confirmed current". Do not present the absence of a hint as proof that the install is up to date. mediaio upgrade is the only unthrottled check, but it also performs the upgrade, so do not run it just to probe.

   • Use a blocking confirmation prompt in the same turn, such as: mediaio reports an update: <Update: line>. Upgrade now?

   • Do not continue with discovery, generation, upload, or wait until the user answers whether to upgrade.

   • If the user says yes, run mediaio upgrade --output json and judge only the standard JSON envelope: schema_version, command, data, and error.

     • A non-zero exit code, or a top-level error, means the upgrade failed. Surface error.message and stop.
     • data.ok=true means the upgrade command completed; continue unless data.cli.scheduled=true.
     • data.cli.scheduled=true (Windows only) means the binary swap happens after the current process exits, so the new CLI is not active in this session yet. Tell the user to restart the session before generating.
     • If data.ok=true and any plugin result has warning, mention it briefly only if useful for diagnostics. Do not treat warnings or skipped_reason as failures.

   • If the user says no, continue only with the currently installed CLI version and do not suppress the hint.

2. Network approval gate (hard requirement). Before launching the first networked mediaio process in the current task, submit that Shell/Bash tool call through the host's narrowest native network-only approval mechanism, scoped to the required destination when supported. Do not first run mediaio account status, auth login, discovery, upload, generation, or wait commands in the default sandbox as a connectivity probe. Approval metadata belongs to the host tool call, not to mediaio CLI arguments.
3. Wait until the approval is accepted or automatically approved before launching the process. If network-only approval is unavailable, use a general out-of-sandbox approval only after reviewing its wider scope and presenting that approval to the user. If the command may write local state (including auth login persisting credentials), also request filesystem-write authorization; do not infer whether the target is inside the sandbox. If the host cannot request the required approval, report the host limitation and stop instead of attempting a known-to-fail sandboxed request. A global Codex permission-profile edit is not a prerequisite.
4. Run mediaio account status using the approved execution path. If authentication is genuinely missing, expired or rejected by the server, run mediaio auth login and wait for the browser flow to finish. DNS, TLS, timeout, connection and sandbox-denial errors are network failures, not authentication failures.
5. On a network or permission failure, load references/troubleshooting.md. Retry read-only commands only after a clear pre-connection sandbox/DNS failure; never automatically retry a write with an ambiguous result.
6. Run mediaio config get when an endpoint or environment mismatch is suspected.

UX Rules

1. Be concise. Do not paste raw registry output or full response payloads unless the user asks for diagnostics.
2. When mediaio version surfaces an Update: line ending with (update available), ask the user whether to run mediaio upgrade --output json before any generation workflow continues. The skill should not silently proceed past an update warning. Because the hint is throttled to once a day, never phrase its absence as a verified "already up to date".
3. Do not expose access tokens, credentials, prompts from unrelated tasks, or request debug payloads.
4. Don't batch-ask. Pick a sane default model from references/model-catalog.md and ask one thing at a time only if genuinely missing.
5. Never invent a job type or parameter. Take the job type from the static catalog and the parameters from model get.
6. Submit first, read the returned task_id=<id> line, then call mediaio generate wait <task_id>. The current generate create command does not accept --wait.
7. Generation spends credits, but do not raise the subject on your own. Submit quietly, and surface the cost or ask for an approval only when the user is cost-sensitive. See the credit handling rules below.
8. Send the user to the web app only through a link the CLI printed. Never compose, complete, or edit a media.io URL, and never name a payment step — see the product-page handoff rules below.

Credit handling

generate create charges the user's Media.io credits. --yes is required on every submission because the CLI otherwise refuses to spend credits from a non-interactive host. By default the CLI prints no cost at all; --show-credit adds the estimate and the balance.

Pick one of three modes

Start in Quiet. Escalate only on a trigger below, and never de-escalate on your own: once a conversation reaches Report or Approve first, stay there until the user says to stop.

Quiet is the default

The user asked for the job, so the request itself is the approval. Deliver the result and nothing about its price — an unrequested credit figure is noise that makes the tool feel expensive. Do not add a confirmation turn, do not run an estimate, and do not mention credits at all.

Escalate to Report

Any one of these, in this turn or earlier in the conversation:

• The user mentioned credits, cost, price, balance, or quota.
• The user asked what a job cost, after it already ran.
• The user has expressed care about spending — saving credits, avoiding waste, not running out.

Report the number the command printed together with the result. One line is enough.

Escalate to Approve first

Any one of these, which are about control rather than visibility:

• The user asked to see the price, estimate, or quote before generating.
• The user objected to an earlier charge, or asked you to check with them before spending.
• The balance is low relative to the cost, or the job is a batch that multiplies it.

Then run the full flow, which stops before spending anything:

1. Estimate. After the parameters are final and any source media is uploaded, run the estimate with the exact job type and parameters you are about to submit:

   mediaio generate estimate <job_type> [--param value]...
   

   The estimate spends nothing. It reports credit, known, rule_type, the billed fields, and the account balance.

2. Ask. Tell the user the job type, the estimated cost, their remaining balance, and that the actual charge is resolved server-side and may be lower. Then ask for approval and end your turn. Do not chain the submission into the same turn.

3. Wait for a real answer. Only a fresh, explicit user message approving this specific job counts. None of the following is approval:

   • the host running in an auto-approve / YOLO mode
   • a shell-command permission prompt the host approved on your behalf
   • your own reasoning that the cost is small

   If the host cannot surface an interactive question to the user, do not submit. Report that the job is ready and is waiting for the user's credit approval.

4. Submit after the approval. Use --yes --show-credit. Optionally add --expect-credit <N> with the number the user approved; the CLI then re-checks the cost and aborts if the parameters drifted. Use it when the cost is large or the parameters were assembled over several steps.

5. If generate create aborts with an --expect-credit mismatch, re-run the estimate, show the new number, and ask again. Do not "fix" a mismatch by changing the number yourself.

6. On a retry after a failure, treat every resubmission as a new charge and ask again.

When the balance runs short

generate estimate, a --show-credit submission, and account status already print a get credits: / get more: line with a ready-made link whenever the balance cannot cover the job. Reuse that line verbatim. If you do not have one — for example a submission was rejected for insufficient credits before any cost was printed — ask the CLI for it:

mediaio link get credits

Then say, in one short line, what the balance is and hand over the printed url unchanged, so the user can pick up or add credits and come back. Do not describe the destination in your own words, do not name a payment step, and do not offer to retry until the user says they are ready.

Never type a media.io URL from memory and never edit one you were given: the destination and its tracking parameters are owned by the binary and can change without a skill update. See the product-page handoff rules below.

Insufficient permission or credits — membership-aware fallback

Trigger: generate estimate, a --show-credit submission, or generate create is rejected because the model requires a membership tier the account does not have, or the balance cannot cover the job.

1. Check the account's membership tier: mediaio account status prints a level: line (free / standard / premium). free means the account is not a paying member.
2. Build your suggestion around that tier — both branches require the user's explicit go-ahead before you act, and both mention the same two options, just in a different order and with different detail:
   • Non-member (free) — lead with the downgrade. Name the specific fallback job_type for this job from the fallback chain in references/model-catalog.md (section 4), so the user knows exactly what they'd get. Mention getting more credits second, with the get credits: link.
   • Member (standard/premium) — lead with getting more credits (the get credits: link). Mention that an alternative/cheaper model is also an option second, but do not name a specific job_type — members do not need to be steered toward the downgraded tier by name.
3. Wait for an explicit yes before doing anything. If the user picks the fallback model, re-run generate estimate for the new job_type (its cost differs) and confirm again per the normal credit rules before submitting. If the user says they'll top up credits instead, stop and wait — do not resubmit on your own once the balance changes; let them tell you they're ready.
4. Never switch models or resubmit without a fresh explicit confirmation, regardless of tier.

Other credit rules

• Never use --skip-estimate. It is for interactive human terminals only and disables the tamper check.
• Never widen spending permissions on your own initiative. mediaio generate auto-confirm on makes every later session spend without asking; only run it when the user asks for that in their own words, and say plainly that auto-confirm off reverts it. Never run it to work around a blocked job or a confirmation required error. mediaio generate auto-confirm status shows what is in effect.
• When the user asks you to stop checking on cost, drop to Report: keep --show-credit and keep saying what each job cost, but stop asking first.

Product-page handoff

The CLI generates; the Media.io web app is where the user browses, organises, and manages what they already have. There are exactly two links, and both come from the CLI:

mediaio link list prints both destinations as purpose, title, url columns.

Rules:

1. Never write a media.io URL yourself, and never rewrite, shorten, or strip parameters from one the CLI printed. The path and its tracking parameters live in the binary precisely so they can change without touching this skill.
2. Answer with the CLI first when the CLI can answer: mediaio generate list covers "what did I run recently", mediaio upload list covers "what have I uploaded". Offer the product page for the full history, previews, and management on top of that.
3. Hand over one link with one line of context. Do not paste both links at once.

Result URL guardrail (hard rule)

A signed Media.io result URL carries a high-entropy storage credential. Rewriting one character breaks it, and the storage service answers InvalidAccessKeyId or SignatureDoesNotMatch rather than pointing at the typo. Therefore:

1. Never retype, re-key, summarise, reformat, or hand-edit a result URL. Do not strip or add query parameters such as x-oss-process, and do not "clean up" the URL for readability.

2. Prefer mediaio generate download. It resolves the task and fetches the file itself, so the download never depends on you reproducing a signed URL. It echoes the source URL on a # url[N] <url> comment line for reference; copy that line verbatim if the user asks for the link.

3. If a raw URL is genuinely required, capture it with the shell instead of copying it. The default brief output prints each result URL flush-left on its own line, so it can be captured verbatim:

   url=$(mediaio generate query <job_type> <task_id> | grep '^http' | head -1)
   

4. If a download fails with a storage credential error, do not attempt to correct the URL. Re-run mediaio generate download <task_id> (or generate query) to obtain a fresh signature.

Output modes

Do not pass --output. Every generate subcommand defaults to brief, which is the only mode you should read:

uni_fun_code is the only field that identifies which model produced a task. The raw algorithm field is combo_alg for every workflow task, so it is omitted from brief output unless it holds a real value (tts, agent2mv, ...). Likewise generate list --algorithm filters by algorithm channel, not by model.

Discovery guardrail — static catalog first

references/model-catalog.md is a generated snapshot of the production registry. It is the default source for model selection. Do not run mediaio model list for routine routing.

Default path (no model list)

1. Read references/model-catalog.md.
2. Pick the job_type from its section 3 routing table — match top-down and stop at the first hit. If the user gave no source image, use the text-to-image table; if they attached one, use the image-to-image table.
3. Some image-to-image rows are conditioned on membership tier. When you reach one, use the level: value already printed by the mediaio account status you ran in the startup sequence — do not run an extra command for it, and treat a missing or unrecognised level as "not a member". Pure text-to-image has a single ToMoviee tier, so membership never changes that pick.
4. Run mediaio model get <job_type> for the parameter schema. This is a required pre-submission step, not a discovery step: the catalog never promises parameters, and you must not infer them from it.
5. Continue with the normal upload / estimate / submit / wait flow.

When you may fall back to model list

Only these cases. Nothing else qualifies.

These are not reasons to call model list: routine intent routing, picking the default model, "let me just double-check", uncertainty about parameters (that is model get), or a job_type that looks misspelled.

Identifier rules (hard requirements)

1. Copy job_type byte for byte. Never trim it, change its case, or "fix" a name that looks wrong. Six production job types contain a literal space, for example image2video_seedance _2.5. Quote them in the shell: mediaio model get "image2video_seedance _2.5".
2. Map display name → job_type only, never the reverse. Display names are frequently unrelated to the identifier: image2image_banana_2 is Nano Banana Pro, while Nano Banana 2 is image2image_nano_banana_2. Look the name up in catalog section 5; do not assemble an identifier from what the user said.
3. Display names are not unique — 37 groups collide. When a name matches several job_type values, list the candidates and let the user choose.
4. ToMoviee is the first-party model family; its Chinese name is 天幕. No model's display name is literally 天幕, so a user asking for 天幕 must be resolved to the ToMoviee entries in catalog section 6.5. Treat 天幕 and ToMoviee as the same request.
5. Echo both when you report your choice: Display Name (job_type).
6. The catalog's permission tier column is a manual annotation. Never promise the user a model is free based on it; the cost comes from generate estimate.

Workflows and effects

Workflows and effects are separate discovery views not covered by the static catalog, but they are submitted through the same command: mediaio generate create <job_type> .... Use mediaio workflow list / mediaio effect list for them. The current CLI has no effect get; never guess effect parameters from the list summary.

mediaio model get <job_type> marks parameters as [workflow-default] when the workflow supplies a value if the flag is omitted.

Workflow — generic generation

1. Select. For models, read references/model-catalog.md and take the job_type from its routing table — see the discovery guardrail above. Run a list command only for a workflow/effect, or when one of the fallback triggers applies:

   mediaio workflow list
   mediaio effect list
   mediaio model list --grep <keyword> --output json   # only on a listed trigger
   

2. Inspect. Use the exact identifier, copied verbatim (quote it if it contains a space):

   mediaio model get <job_type>
   mediaio workflow get <workflow_name>
   

   For an effect, stop if its required parameters have not already been verified from current BIN/service evidence; effect list alone is not a parameter schema.

3. Prepare local media and check file access. The current generator does not auto-upload local paths. Before reading or uploading each user-provided path:

   • Confirm the job actually needs source media, then confirm the user supplied it. Job types named like image2image_*, image2video_*, img2vid_*, *_i2i, *_i2v, or reference2video_*, and any job whose model get/workflow get output lists an image/video/reference parameter, need at least one uploaded source file — even when the live schema does not mark that parameter required. If the user has not attached or referenced a local file or an existing file_id for such a job type, stop before generate create and ask the user to provide the source image/video first. Do not submit the job and then rely on the server's error to tell you a source was missing; see references/troubleshooting.md for the failure signature.
   • Resolve relative paths against the current working directory without following an untrusted path blindly, and determine whether the resolved file is inside the active workspace.
   • For a path inside the workspace, continue with the normal host file-read rules.
   • For a path outside the workspace, pause and request the host's native file-read authorization for the exact file (or the smallest explicit set of files). State the paths and that they will be uploaded to Media.io. Do not launch mediaio upload create until that authorization is accepted.
   • If the host cannot provide file-read authorization, stop and ask the user to grant access or move/copy the file into the workspace. Never bypass this by broadening access silently.

   After the required file authorization and network approval are available, upload each local file first, save the returned file_id, then pass that ID using the exact parameter name shown by model get or workflow get:

   mediaio upload create ./reference.png
   

4. Pick the credit mode. Apply the credit handling rules above: stay Quiet unless the conversation has already triggered Report (add --show-credit to the submission below) or Approve first (estimate and stop for an answer before submitting).

5. Submit. Pass only parameters exposed by the live schema, plus --yes:

   mediaio generate create <job_type> [--param value]... --yes
   

   Do not mention the cost when you deliver the result unless --show-credit was warranted.

6. Wait. Read the task_id=<id> line printed by the create command, then run:

   mediaio generate wait <task_id> --timeout 20m --interval 3s
   

   When the deliverable is a local file, let the CLI do the download in the same step and skip URL handling entirely:

   mediaio generate wait <task_id> --timeout 20m --download "$(mktemp -d)"
   

7. Deliver. Retrieve every result file with the CLI, never by re-entering, re-fetching, or hand-copying a URL. Do not run curl/wget/a browser against a result URL yourself, even to "double check" it — that is exactly how a 430-510 character signed URL gets corrupted. If a fetch fails, re-run generate download/generate query for a fresh signature instead of retrying your own copy of the URL.

   1. Create a writable temporary directory with mktemp -d.

   2. Download the task's results into it:

      mediaio generate download <task_id> --output-dir "$tmp_dir"
      

      Every non-comment line is a local path; each file is preceded by a # file[N] ... metadata line and a # url[N] <url> line carrying the source URL. Use grep -v '^#' to keep only the paths. Omit --index so every result file is downloaded — a task can produce more than one. Use --index N only when the user explicitly wants a single specific result, and --variant preview only when they explicitly want the compressed preview instead of the full-resolution file. --variant original is the default and is what you should normally deliver.

   3. For each downloaded path (not just the first), require a non-empty file, then inspect it with file --brief --mime-type "$download_path". Continue with the image path only for image/*. If the CLI-provided filename already carries an accurate extension, keep it; otherwise derive one from common MIME types (image/png → png, image/jpeg → jpg, image/webp → webp, image/gif → gif). Never label an unknown image as PNG.

   4. Deliver every verified file back to the host as its own local-path Markdown image, in the same order generate download printed them, using the standard syntax ![preview](<local-path>). A task with N result files means N images in the reply — never stop after the first one. When a local path contains spaces, parentheses, or non-ASCII characters, wrap the target in angle brackets. Prefer the local downloaded file over the remote HTTPS URL.

   5. Report completion only after providing the local Markdown image snippet, or after establishing that local-path Markdown cannot be used in the current host. In the latter case, explicitly say inline local preview is unavailable, and reuse the # url[N] line printed by generate download (or the shell capture shown in the result URL guardrail) rather than transcribing the URL.

   6. Do not remove the temporary directory before the final response is sent, because the host may resolve the local Markdown path when rendering the reply.

   7. curl is a fallback only when generate download is unavailable in the installed build. In that case still capture the URL into a shell variable and pass "$url" unmodified:

      curl --fail --location --retry 2 \
        --connect-timeout 15 --max-time 120 \
        --output "$download_path" "$url"
      

   For video, audio, 3D, or other non-image outputs, download the file the same way and give the user its local path; provide the result URL only when the host cannot accept a local file.

Verified image generation

For text-only GPT Image 2, current discovery exposes text2image_gpt_image_2 with --prompt, --n, --quality, --model, --size, and --output_format.

mediaio model get text2image_gpt_image_2
mediaio generate create text2image_gpt_image_2 \
  --prompt "a warm, photorealistic portrait of a golden retriever at sunset" \
  --quality high \
  --size 1024x1024 \
  --output_format png \
  --yes

Do not replace this with the legacy short name gpt_image_2; it is not the current registry key. Do not append --wait to the create command. When the user is cost-sensitive, add --show-credit so the cost is printed, and price the job with mediaio generate estimate first if they want a say before spending.

For image-to-image GPT Image 2, upload each source first and use the live repeated flag --images <file_id> with image2image_gpt_image_2.

Current capability boundary

Only the command families printed by the current mediaio --help output are executable, and only the job_type values present in references/model-catalog.md (or returned by live discovery) exist. The migrated reference set also describes surfaces that are not part of the current BIN:

• workflow-specific create helpers
• one-shot create-and-wait flags
• automatic upload of local paths passed directly to generation parameters
• 3D, audio, Virality Predictor, Soul ID, product-photoshoot, game-generation, or video-explainer routes — the production registry has no fun_module for these at all

Errors

• flag provided but not defined: -wait → remove --wait, submit, then call mediaio generate wait <task_id>.
• credit confirmation required: rerun with --yes ... → --yes was missing. Add it. If the user is cost-sensitive, add --show-credit too, and get their approval before resubmitting. Never satisfy this error with --skip-estimate or by turning on auto-confirm.
• a submission or estimate rejected because the balance cannot cover the job, or because the model requires a membership tier the account does not have → do not retry and do not switch to a cheaper model on your own. Follow "Insufficient permission or credits — membership-aware fallback" above and wait for the user.
• credit estimate mismatch: --expect-credit X but the current parameters estimate to Y → the parameters changed after the approval. Show Y to the user and ask again; never silently resubmit with Y.
• --skip-estimate is only allowed on an interactive terminal → drop the flag so the cost is printed.
• --json is not supported; use --output json instead or flag provided but not defined: -json → drop --json; you should not be passing an output flag at all.
• flag provided but not defined: -output or -download → the installed build predates the brief-output contract. Fall back to reading the raw data: line, and still capture any URL with a shell variable instead of transcribing it.
• unknown job type → most often the identifier was altered. Re-read it from references/model-catalog.md and copy it byte for byte; check section 6.1 in case it contains a space. Only if it is genuinely absent from the catalog, rerun the relevant live list and use its exact first-column identifier, and tell the user the catalog looks stale.
• missing required flag(s) or invalid value → inspect the live schema and pass only exposed values.
• InvalidAccessKeyId, SignatureDoesNotMatch, or an HTTP 403 from the storage host while downloading → the URL was altered or has expired. Do not try to repair it. Re-run mediaio generate download <task_id>.
• is not downloadable yet: status=... → the task has not reached a successful terminal state; run generate wait first and read reason_code/reason_label.
• already exists; pass --overwrite to replace it → choose a fresh --output-dir (for example a new mktemp -d) or pass --overwrite deliberately.
• task is accepted but generate wait ends in a generic terminal failure → before retrying, check whether the job type needs a source image/video (name contains image2image/image2video/img2vid/reference2video, or model get/workflow get lists an image/video parameter). If no source file was uploaded and passed for such a job, ask the user for one and resubmit; do not blindly retry the identical command. See references/troubleshooting.md for the specific error signature.
• endpoint 404 during create → verify the BIN build routes creation through the configured combo_alg endpoint; do not switch models because this is not a prompt/model-selection error.
• missing credentials, an HTTP 401, or an explicit token-refresh rejection → run mediaio auth login.

Reference docs

Load references on demand:

• references/model-catalog.md before every model selection — generated from the production registry; carries the defaults, routing rules, fallback chain, the full model index, and the known identifier traps
• references/prompt-engineering.md for prompt-writing guidance
• references/media-inputs.md when the user provides local or uploaded media
• references/workflows.md for a job type returned by live workflow discovery
• references/troubleshooting.md after a current command fails