muapi-media

MuAPI Media

Overview

Use MuAPI's unified asynchronous API for image and video generation when a

workflow needs model choice without a separate integration for every provider.

The catalog and each model's input schema are authoritative; this skill does

not guess fields, bundle an SDK, or hide a billable generation request. For a

capability overview, see the MuAPI AI video API.

When to Use This Skill

• Use when the user explicitly asks to generate an image or video with MuAPI.
• Use when an existing media workflow needs a hosted asynchronous API and can

send an authorized HTTPS request.

• Use when the user needs to compare or switch among current media models

without changing the surrounding submit-and-poll workflow.

• Do not use this skill for text chat or for a provider whose current schema

has not been fetched and checked.

Preconditions

1. Confirm that the user is authorized to send the prompt and any reference

media to a third-party service.

1. Explain that generation may be billable and obtain approval immediately

before the generation request.

1. Require MUAPI_API_KEY in the environment. Never ask the user to paste it

into chat, source files, command history, or logs.

1. Confirm the requested media type, output location, and whether the user

wants a single generation or an explicitly approved batch.

API Contract

| Operation | Method and endpoint |

| --- | --- |

| List current models | GET https://api.muapi.ai/api/v1/models |

| Read one model's schema | GET https://api.muapi.ai/api/v1/models/{model} |

| Submit a generation | POST https://api.muapi.ai/{catalog endpoint} |

| Poll a prediction | GET https://api.muapi.ai/api/v1/predictions/{request_id}/result |

Generation and prediction requests use:

x-api-key: $MUAPI_API_KEY
Content-Type: application/json

The catalog returns a model name, category, endpoint, and other metadata. The

endpoint value already includes /api/v1/; append it to https://api.muapi.ai

without adding a second version prefix. Model input and output fields vary, so

read the selected model's schema immediately before preparing a request.

How It Works

1. Discover and validate a model

Use a temporary directory for response files and keep credentials out of every

file. The catalog lookup is read-only:

workdir=$(mktemp -d "${TMPDIR:-/tmp}/muapi-media.XXXXXX")

curl --fail --silent --show-error \
  --header "Accept: application/json" \
  "https://api.muapi.ai/api/v1/models" \
  --output "$workdir/models.json"

jq -r '
  .models[]
  | select(((.category // "") | ascii_downcase | test("image|video|audio|3d")))
  | [.name, .category, .endpoint]
  | @tsv
' "$workdir/models.json"

Select a model from the current catalog, then fetch its detailed schema. Do

not copy a payload from a different model just because the names look similar:

export MUAPI_MODEL="<model name from the catalog>"

curl --fail --silent --show-error \
  --header "Accept: application/json" \
  "https://api.muapi.ai/api/v1/models/${MUAPI_MODEL}" \
  --output "$workdir/model.json"

jq '.input_schema.schemas.input_data' "$workdir/model.json"

Check required fields, types, enum values, size limits, and the output schema.

If the model requires an image or video input, use the exact documented field

and an authorized HTTPS input URL; do not invent an upload contract.

2. Prepare one reviewed request

Set the key only in the environment and stop before submission if it is absent:

test -n "${MUAPI_API_KEY:-}" || {
  echo "Set MUAPI_API_KEY before generation." >&2
  exit 1
}

export MUAPI_PROMPT="A small paper boat crossing a calm pond at sunrise, steady camera"

# Add only fields confirmed by model.json. This example uses a prompt field;
# many models also require duration, resolution, aspect ratio, or an input URL.
jq -n \
  --arg prompt "$MUAPI_PROMPT" \
  '{prompt: $prompt}' \
  > "$workdir/request.json"

Review the model, requested parameters, destination, and estimated cost with

the user. Do not put MUAPI_API_KEY in request.json.

3. Submit exactly once

Resolve the catalog endpoint and make one POST. Do not automatically retry a

generation POST after a timeout: the original task may have been accepted.

model_endpoint=$(jq -er --arg name "$MUAPI_MODEL" '
  .models[]
  | select(.name == $name)
  | .endpoint
  | select(type == "string" and startswith("/api/v1/"))
' "$workdir/models.json")

curl --fail --silent --show-error \
  --request POST \
  "https://api.muapi.ai${model_endpoint}" \
  --header @- \
  --header "Content-Type: application/json" \
  --data "@$workdir/request.json" \
  --output "$workdir/submit.json" <<EOF
x-api-key: ${MUAPI_API_KEY}
EOF

request_id=$(jq -er '
  .request_id // .id // .data.request_id // .data.id // .output.id
  | select(type == "string" and length > 0)
' "$workdir/submit.json")

Keep the request ID for diagnosis. Never print request headers or the key.

4. Poll with a finite deadline

Poll the original request ID, accept only documented terminal states, and stop

after a bounded number of attempts. The response shape can vary, so use the

selected model's output schema when extracting the result URL:

result_url="https://api.muapi.ai/api/v1/predictions/${request_id}/result"

for attempt in $(seq 1 120); do
  curl --fail --silent --show-error \
    "$result_url" \
    --header @- \
    --output "$workdir/result.json" <<EOF
x-api-key: ${MUAPI_API_KEY}
EOF

  status=$(jq -r '.status // .data.status // .output.status // "unknown"' \
    "$workdir/result.json")
  case "$status" in
    completed|succeeded|success) break ;;
    failed|error|canceled|cancelled|timeout)
      jq -r '.error // .data.error // .output.error // "MuAPI generation failed"' \
        "$workdir/result.json" >&2
      exit 1
      ;;
  esac
  sleep 2
done

test "$status" = completed \
  || test "$status" = succeeded \
  || test "$status" = success

Do not create a second paid task merely because polling was interrupted. First

poll the known request ID again and inspect its sanitized status.

5. Download without the API key

Extract an HTTPS output URL using the model's output schema. Download it with

a fresh request that has no MuAPI header, validate the file, and only then

return or publish it:

output_url=$(jq -er '
  .output.outputs[0]
  // .data.output.outputs[0]
  // .outputs[0]
  // .data.outputs[0]
  // .output.video
  // .data.output.video
  | select(type == "string" and startswith("https://"))
' "$workdir/result.json")

curl --fail --silent --show-error \
  "$output_url" \
  --output "$workdir/output.bin"

test -s "$workdir/output.bin"
file "$workdir/output.bin"

Do not add x-api-key to this request. Reject non-HTTPS output URLs, avoid

following unvalidated redirects, and use a downloader that checks each

redirect destination and DNS result when the service returns a redirecting or

user-controlled URL. Never execute a downloaded file as code.

Examples

Read-only model discovery

curl --fail --silent --show-error \
  "https://api.muapi.ai/api/v1/models" \
  | jq -r '.models[] | [.name, .category, .endpoint] | @tsv'

One text-to-video request

1. Discover a current Text to Video model.
2. Fetch its detailed input_schema and confirm that prompt and the requested
   duration/resolution fields are accepted.
3. Obtain approval, submit one POST with MUAPI_API_KEY, and save request_id.
4. Poll the result endpoint at most 120 times.
5. Download the HTTPS output without the API key and validate the video file.

Best Practices

• Treat the live model catalog and detailed schema as authoritative.
• Keep each generation request explicit and obtain approval before billable

work.

• Submit one POST per task; retry only bounded, idempotent GET polling.
• Use a finite polling deadline and preserve the request ID on failure.
• Keep API keys in the environment or an approved secret manager.
• Use temporary files with restrictive local permissions and remove sensitive

response data after the workflow finishes.

• Validate HTTPS output URLs, size, content type, and basic image/video decode

before handing media to another tool.

• Respect prompt rights, model restrictions, and the user's consent for any

uploaded reference media.

Limitations

• This is an instruction-only skill; it does not install an SDK or background

worker.

• Models, schemas, prices, output retention, and supported fields can change;

the live catalog is authoritative.

• Generation is asynchronous and may take minutes or fail after submission.
• Output URLs can expire and may not be reusable as permanent asset links.
• A successful HTTP response does not guarantee a valid or usable media file.
• This skill does not replace human review of media quality, rights, safety, or

provider policy compliance.

Security & Safety Notes

• Treat prompts and reference media as data sent to a third party; obtain

consent and avoid unnecessary personal or confidential information.

• Never log, echo, commit, or include MUAPI_API_KEY in JSON payloads or

process arguments; pass authenticated curl headers through protected stdin or

a protected config file.

• Do not forward the API key to output hosts, redirects, browser URLs, or

user-controlled domains.

• Do not use this workflow for bulk generation, file hosting, or unrelated

network transfers without explicit authorization.

• Keep generated media in a controlled output directory and inspect it before

opening or sharing it.

Common Pitfalls

• Problem: The API returns a validation error.

Solution: Fetch the selected model's current schema and rebuild the

payload from its required fields and allowed values.

• Problem: A timeout occurs immediately after POST.

Solution: Preserve the request ID if available and poll it before

considering any resubmission.

• Problem: The output is HTML, JSON, or an empty file.

Solution: Check the HTTPS URL, response status, content type, file size,

and basic media decode before treating it as generated output.

• Problem: A download request would send the API key to a CDN.

Solution: Create a fresh header-free download request and validate every

redirect destination.

Additional Resources

• MuAPI API reference for authentication,

request lifecycle, and endpoint details.

• MuAPI AI video API for current video

capabilities and model-oriented discovery.