MiniMax-AI · Ray0907 · Aug 11, 2026
diff --git a/scripts/readme/common.sh b/scripts/readme/common.sh
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+
+# Override these values to tune long-running job polling and transient GET retries.
+POLL_INTERVAL_SECONDS=${POLL_INTERVAL_SECONDS:-10}
+POLL_TIMEOUT_SECONDS=${POLL_TIMEOUT_SECONDS:-7200}
+HTTP_RETRY_COUNT=${HTTP_RETRY_COUNT:-3}
+HTTP_RETRY_DELAY_SECONDS=${HTTP_RETRY_DELAY_SECONDS:-2}
+HTTP_CONNECT_TIMEOUT_SECONDS=${HTTP_CONNECT_TIMEOUT_SECONDS:-10}
+HTTP_REQUEST_TIMEOUT_SECONDS=${HTTP_REQUEST_TIMEOUT_SECONDS:-60}
+
+curlWithRetry() {
+	curl --fail-with-body --silent --show-error \
+		--retry "$HTTP_RETRY_COUNT" \
+		--retry-all-errors \
+		--retry-delay "$HTTP_RETRY_DELAY_SECONDS" \
+		--connect-timeout "$HTTP_CONNECT_TIMEOUT_SECONDS" \
+		"$@"
+}
+
+pollJob() {
+	local url_query=$1
+	local filter_status=$2
+	shift 2
+
+	local response_job
+	local status_job
+	local status_normalized
+	local time_started=$SECONDS
+
+	while ((SECONDS - time_started < POLL_TIMEOUT_SECONDS)); do
+		if ! response_job=$(
+			curlWithRetry --max-time "$HTTP_REQUEST_TIMEOUT_SECONDS" \
+				--request GET --url "$url_query" "$@"
+		); then
+			printf 'Failed to query async job: %s\n' "$url_query" >&2
+			return 1
+		fi
+
+		if ! status_job=$(printf '%s\n' "$response_job" | jq -er "$filter_status"); then
+			printf 'Async job response has no valid status: %s\n' "$response_job" >&2
+			return 1
+		fi
+
+		status_normalized=$(printf '%s' "$status_job" | tr '[:upper:]' '[:lower:]')
+		printf 'Async job status: %s\n' "$status_job" >&2
+
+		case "$status_normalized" in
+			completed | success | succeeded | finished | done)
+				printf '%s\n' "$response_job"
+				return 0
+				;;
+			failed | failure | fail | error | cancelled | canceled)
+				printf 'Async job failed: %s\n' "$response_job" >&2
+				return 1
+				;;
+			queued | queueing | preparing | processing | running | pending | in_progress | in-progress)
+				;;
+			*)
+				printf 'Unexpected async job status: %s\n' "$status_job" >&2
+				return 1
+				;;
+		esac
+
+		sleep "$POLL_INTERVAL_SECONDS"
+	done
+
+	printf 'Async job timed out after %s seconds: %s\n' \
+		"$POLL_TIMEOUT_SECONDS" "$url_query" >&2
+	return 124
+}
+
+pollSglangVideo() {
+	local url_base=$1
+	local id_video=$2
+
+	pollJob "$url_base/v1/videos/$id_video" '.status'
+}
+
+pollMiniMaxTask() {
+	local url_base=$1
+	local token_api=$2
+	local id_task=$3
+
+	pollJob "$url_base/v2/query/video_generation/$id_task" \
+		'.task.status // .status' \
+		--header "Authorization: Bearer $token_api"
+}
diff --git a/scripts/readme/full-2k-i2va-h3-base.sh b/scripts/readme/full-2k-i2va-h3-base.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create the H3-Base request with the expanded prompt and capture the video ID.
 video_id=$(
@@ -30,13 +31,10 @@ video_id=$(
       --data-binary @- |
     jq -er '.id'
 )
-# Query the generation status.
-curl --silent --show-error \
-  --request GET \
-  --url "$SGLANG_DEPLOYMENT_URL/v1/videos/$video_id" |
-  jq '{status}'
+# Poll until generation completes, fails, or times out.
+pollSglangVideo "$SGLANG_DEPLOYMENT_URL" "$video_id" >/dev/null
 # Download the local H3-Base MP4 after its status becomes completed.
-curl --silent --show-error \
+curlWithRetry --location \
   --request GET \
   --url "$SGLANG_DEPLOYMENT_URL/v1/videos/$video_id/content" \
   --output i2va.mp4
diff --git a/scripts/readme/full-2k-i2va-h3-context-ir.sh b/scripts/readme/full-2k-i2va-h3-context-ir.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create the prompt-expansion task and capture its runtime ID.
 task_id=$(
@@ -28,13 +29,8 @@ task_id=$(
 }' |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-context_ir_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until prompt expansion completes, fails, or times out.
+context_ir_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$context_ir_result" | jq .
 # Export the complete expanded prompt for H3-Base and regeneration.
 EXPANDED_PROMPT=$(echo "$context_ir_result" | jq -er '.task.content.prompt')
diff --git a/scripts/readme/full-2k-i2va-h3-regenerate-2k.sh b/scripts/readme/full-2k-i2va-h3-regenerate-2k.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 H3_BASE_VIDEO='./i2va.mp4'
 # Encode the local H3-Base video as a Data URL and create the regeneration task.
@@ -42,14 +43,9 @@ task_id=$(
       --data-binary @- |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-regeneration_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until regeneration completes, fails, or times out.
+regeneration_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$regeneration_result" | jq '{status: .task.status}'
 # Download the 2K MP4 after the task succeeds.
 video_url=$(echo "$regeneration_result" | jq -er '.task.content.url')
-curl --location "$video_url" --output i2va_2k.mp4
+curlWithRetry --location "$video_url" --output i2va_2k.mp4
diff --git a/scripts/readme/full-2k-i2va-reference-2k-result-by-directly-calling-open-platform-api.sh b/scripts/readme/full-2k-i2va-reference-2k-result-by-directly-calling-open-platform-api.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create an 8-second 2K FL2VA video directly and capture its runtime task ID.
 task_id=$(
@@ -29,14 +30,9 @@ task_id=$(
 }' |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-generation_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until generation completes, fails, or times out.
+generation_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$generation_result" | jq '{status: .task.status}'
 # Download the 2K MP4 after the task succeeds.
 video_url=$(echo "$generation_result" | jq -er '.task.content.url')
-curl --location "$video_url" --output i2va_direct_2k.mp4
+curlWithRetry --location "$video_url" --output i2va_direct_2k.mp4
diff --git a/scripts/readme/full-2k-i2va-reference-768p-result-by-directly-calling-open-platform-api.sh b/scripts/readme/full-2k-i2va-reference-768p-result-by-directly-calling-open-platform-api.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create an 8-second 768P FL2VA video directly and capture its runtime task ID.
 task_id=$(
@@ -29,14 +30,9 @@ task_id=$(
 }' |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-generation_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until generation completes, fails, or times out.
+generation_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$generation_result" | jq '{status: .task.status}'
 # Download the 768P MP4 after the task succeeds.
 video_url=$(echo "$generation_result" | jq -er '.task.content.url')
-curl --location "$video_url" --output i2va_direct_768p.mp4
+curlWithRetry --location "$video_url" --output i2va_direct_768p.mp4
diff --git a/scripts/readme/full-2k-ref2va-h3-api-2k-in-open-platform-for-reference.sh b/scripts/readme/full-2k-ref2va-h3-api-2k-in-open-platform-for-reference.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create a 5-second 2K Ref2VA video directly and capture its runtime task ID.
 task_id=$(
@@ -36,14 +37,9 @@ task_id=$(
 }' |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-generation_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until generation completes, fails, or times out.
+generation_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$generation_result" | jq '{status: .task.status}'
 # Download the 2K MP4 after the task succeeds.
 video_url=$(echo "$generation_result" | jq -er '.task.content.url')
-curl --location "$video_url" --output r2va_direct_2k.mp4
+curlWithRetry --location "$video_url" --output r2va_direct_2k.mp4
diff --git a/scripts/readme/full-2k-ref2va-h3-base.sh b/scripts/readme/full-2k-ref2va-h3-base.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create the H3-Base request with the expanded prompt and capture the video ID.
 video_id=$(
@@ -34,13 +35,10 @@ video_id=$(
       --data-binary @- |
     jq -er '.id'
 )
-# Query the generation status.
-curl --silent --show-error \
-  --request GET \
-  --url "$SGLANG_DEPLOYMENT_URL/v1/videos/$video_id" |
-  jq '{status}'
+# Poll until generation completes, fails, or times out.
+pollSglangVideo "$SGLANG_DEPLOYMENT_URL" "$video_id" >/dev/null
 # Download the local H3-Base MP4 after its status becomes completed.
-curl --silent --show-error \
+curlWithRetry --location \
   --request GET \
   --url "$SGLANG_DEPLOYMENT_URL/v1/videos/$video_id/content" \
   --output r2va.mp4
diff --git a/scripts/readme/full-2k-ref2va-h3-context-ir.sh b/scripts/readme/full-2k-ref2va-h3-context-ir.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create the prompt-expansion task and capture its runtime ID.
 task_id=$(
@@ -35,13 +36,8 @@ task_id=$(
 }' |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-context_ir_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until prompt expansion completes, fails, or times out.
+context_ir_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$context_ir_result" | jq .
 # Export the complete expanded prompt for H3-Base and regeneration.
 EXPANDED_PROMPT=$(echo "$context_ir_result" | jq -er '.task.content.prompt')
diff --git a/scripts/readme/full-2k-ref2va-reference-2k-result-by-directly-calling-open-platform-api.sh b/scripts/readme/full-2k-ref2va-reference-2k-result-by-directly-calling-open-platform-api.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 H3_BASE_VIDEO='./r2va.mp4'
 # Encode the local H3-Base video as a Data URL and create the regeneration task.
@@ -49,14 +50,9 @@ task_id=$(
       --data-binary @- |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-regeneration_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until regeneration completes, fails, or times out.
+regeneration_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$regeneration_result" | jq '{status: .task.status}'
 # Download the 2K MP4 after the task succeeds.
 video_url=$(echo "$regeneration_result" | jq -er '.task.content.url')
-curl --location "$video_url" --output r2va_2k.mp4
+curlWithRetry --location "$video_url" --output r2va_2k.mp4
diff --git a/scripts/readme/full-2k-ref2va-reference-768p-result-by-directly-calling-open-platform-api.sh b/scripts/readme/full-2k-ref2va-reference-768p-result-by-directly-calling-open-platform-api.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create a 5-second 768P Ref2VA video directly and capture its runtime task ID.
 task_id=$(
@@ -36,14 +37,9 @@ task_id=$(
 }' |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-generation_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until generation completes, fails, or times out.
+generation_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$generation_result" | jq '{status: .task.status}'
 # Download the 768P MP4 after the task succeeds.
 video_url=$(echo "$generation_result" | jq -er '.task.content.url')
-curl --location "$video_url" --output r2va_direct_768p.mp4
+curlWithRetry --location "$video_url" --output r2va_direct_768p.mp4
diff --git a/scripts/readme/full-2k-t2va-h3-base.sh b/scripts/readme/full-2k-t2va-h3-base.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create the H3-Base request with the expanded prompt and capture the video ID.
 video_id=$(
@@ -23,13 +24,10 @@ video_id=$(
       --data-binary @- |
     jq -er '.id'
 )
-# Query the generation status.
-curl --silent --show-error \
-  --request GET \
-  --url "$SGLANG_DEPLOYMENT_URL/v1/videos/$video_id" |
-  jq '{status}'
+# Poll until generation completes, fails, or times out.
+pollSglangVideo "$SGLANG_DEPLOYMENT_URL" "$video_id" >/dev/null
 # Download the local H3-Base MP4 after its status becomes completed.
-curl --silent --show-error \
+curlWithRetry --location \
   --request GET \
   --url "$SGLANG_DEPLOYMENT_URL/v1/videos/$video_id/content" \
   --output t2va.mp4
diff --git a/scripts/readme/full-2k-t2va-h3-context-ir.sh b/scripts/readme/full-2k-t2va-h3-context-ir.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/common.sh"
 
 # Create the prompt-expansion task and capture its runtime ID.
 task_id=$(
@@ -21,13 +22,8 @@ task_id=$(
 }' |
     jq -er '.task_id'
 )
-# Query again while the task is queued or running.
-context_ir_result=$(
-  curl --silent --show-error \
-    --request GET \
-    --url "$MINIMAX_API_BASE/v2/query/video_generation/$task_id" \
-    --header "Authorization: Bearer $TOKEN"
-)
+# Poll until prompt expansion completes, fails, or times out.
+context_ir_result=$(pollMiniMaxTask "$MINIMAX_API_BASE" "$TOKEN" "$task_id")
 echo "$context_ir_result" | jq .
 # Export the complete expanded prompt for H3-Base and regeneration.
 EXPANDED_PROMPT=$(echo "$context_ir_result" | jq -er '.task.content.prompt')