Video Reverse Prompt#

Analyze videos to extract detailed shot breakdowns and AI-ready prompts via the NanoPhoto.AI API.

Use the bundled script for local file uploads instead of inlining large base64 payloads directly in the shell; it is more reliable for multi-megabyte videos.

Prerequisites#

1. Obtain an API key at: https://nanophoto.ai/settings/apikeys
2. Configure NANOPHOTO_API_KEY before using the skill.

Preferred OpenClaw setup:

• Open the skill settings for this skill
• Add an environment variable named NANOPHOTO_API_KEY
• Paste the API key as its value

Equivalent config shape:

json

{
  "skills": {
    "entries": {
      "video-reverse-prompt": {
        "enabled": true,
        "env": {
          "NANOPHOTO_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Other valid ways to provide the key:

• Shell: export NANOPHOTO_API_KEY="your_api_key_here"
• Tool-specific env config: any runtime that injects NANOPHOTO_API_KEY

Credential declaration summary:

• Required env var: NANOPHOTO_API_KEY
• Primary credential: NANOPHOTO_API_KEY
• No unrelated credentials are required

If the env var is not set, ask the user to configure it before proceeding.

Workflow#

1. Collect the video source from the user (YouTube link, direct .mp4 URL, or local file path)
2. Determine videoSource type: youtube, url, or file
3. Confirm the user is authorized to upload or process the content
4. If local file: read and base64-encode it (must be .mp4, max 30 MB)
5. Call the API (streaming response)
6. Return the shot breakdown and prompts to the user

API Call#

YouTube Video#

bash

curl -X POST "https://nanophoto.ai/api/sora-2/reverse-prompt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NANOPHOTO_API_KEY" \
  --data-raw '{
    "videoSource": "youtube",
    "locale": "en",
    "videoUrl": "https://www.youtube.com/watch?v=XXXXXXXXXXX"
  }'

Direct Video URL#

bash

curl -X POST "https://nanophoto.ai/api/sora-2/reverse-prompt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NANOPHOTO_API_KEY" \
  --data-raw '{
    "videoSource": "url",
    "locale": "en",
    "videoUrl": "https://example.com/video.mp4"
  }'

Local File (Preferred: bundled script)#

bash

python3 scripts/reverse_prompt_file.py your-video.mp4 --locale en

The script reads NANOPHOTO_API_KEY from the environment, validates the file size/format, base64-encodes the MP4, and prints the streaming text response.

Local File (Manual Base64 request)#

bash

VIDEO_BASE64=$(base64 < your-video.mp4)

curl -X POST "https://nanophoto.ai/api/sora-2/reverse-prompt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NANOPHOTO_API_KEY" \
  --data-raw "{
    \"videoSource\": \"file\",
    \"locale\": \"en\",
    \"videoFile\": \"$VIDEO_BASE64\",
    \"videoFileName\": \"your-video.mp4\"
  }"

Parameters#

ParameterTypeRequiredDescriptionvideoSourcestringYesyoutube, url, or file``localestringNoOutput language (default: en). Supported: en, zh, zh-TW, ja, ko, es, fr, de, pt, ru, ar``videoUrlstringConditionalYouTube link or direct .mp4 URLvideoFilestringConditionalBase64-encoded video (when videoSource is file)videoFileNamestringNoOriginal filename for uploaded videos

Constraints#

• Only .mp4 format supported
• Max file size: 30 MB (before base64 encoding)
• videoFile accepts plain base64 or Data URL ( data:video/mp4;base64,...)
• Costs 1 credit per API call

Response#

The API returns a streaming text response ( Content-Type: text/plain; charset=utf-8) containing a Markdown table with:

• Shot number, framing/angle, camera movement
• Detailed visual description
• Audio analysis (BGM, sound effects, narration)
• Duration per shot
• Overall summary

Error Handling#

errorCodeHTTPCauseActionLOGIN_REQUIRED401Invalid or missing API keyVerify key at https://nanophoto.ai/settings/apikeysAPI_KEY_RATE_LIMIT_EXCEEDED429Rate limit exceededWait and retryINSUFFICIENT_CREDITS402Not enough creditsTop up creditsINVALID_INPUT400Missing required parametersCheck videoSource and corresponding fieldsINVALID_YOUTUBE_URL400Invalid YouTube URLAsk user for a valid YouTube linkINVALID_VIDEO_URL400Invalid video URLAsk user for a valid .mp4 URLINVALID_FORMAT400Not MP4 formatOnly .mp4 is supportedFILE_TOO_LARGE400File exceeds 30 MBAsk user for a smaller fileVIDEO_DOWNLOAD_FAILED400Cannot download videoCheck URL accessibilityVIDEO_PROCESSING_FAILED422Processing errorRetry or try a different videoAI_SERVICE_ERROR503AI service unavailableRetry later

Bundled script#

• scripts/reverse_prompt_file.py: Reliable local-file uploader for .mp4 inputs. Use it when the user provides a local video path.

Full API Reference#

See references/api.md for complete endpoint documentation.