Veo 3.1#

Generate videos through the NanoPhoto.AI Veo 3.1 API.

Prerequisites#

1. Obtain an API key at: https://nanophoto.ai/settings/apikeys
2. Configure NANOPHOTO_API_KEY before using the skill.
3. Do not paste the API key into chat; store it in the platform's secure env setting for this 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": {
      "veo-3-1": {
        "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
• OpenClaw config fallback: the bundled script also falls back to ~/.openclaw/openclaw.json at skills.entries.veo-3-1.env.NANOPHOTO_API_KEY

Credential declaration summary:

• Primary credential: NANOPHOTO_API_KEY
• Resolution order in the bundled script: --api-key → NANOPHOTO_API_KEY environment variable → ~/.openclaw/openclaw.json skill env
• No unrelated credentials are required

Recommended workflow#

1. Build a shots array.

2. For each shot, set id, prompt, generationType, and aspectRatio.

3. Add public imageUrls only when the generation type requires them.

4. Choose resolution.

   • Use 720p by default.
   • Use 1080p or 4k only for single-shot jobs.

5. Submit the generation request.

6. If the user wants synchronous progress output in the same process, use submit --follow.

7. Poll every 5-10 seconds until completed or failed.

8. Return final shot-level videoUrl values and timing information when available.

Shot rules#

• Max 21 shots total
• Each shot is 8 seconds
• Max total runtime is 168 seconds
• TEXT_2_VIDEO
  • No imageUrls
• FIRST_AND_LAST_FRAMES_2_VIDEO
  • Requires 1-2 public imageUrls
• REFERENCE_2_VIDEO
  • Requires 1-3 public imageUrls

Preferred commands#

Use the single bundled script with subcommands.

Submit a single text-to-video shot#

bash

python3 scripts/veo_3_1.py submit \
  --shots-json '[{"id":"shot-1","prompt":"A golden retriever running on a beach at sunset, cinematic lighting","generationType":"TEXT_2_VIDEO","aspectRatio":"16:9"}]' \
  --resolution 720p

Submit a reference-image shot and keep polling#

bash

python3 scripts/veo_3_1.py submit \
  --shots-json '[{"id":"shot-1","prompt":"The character comes alive, walking through a magical forest","generationType":"REFERENCE_2_VIDEO","aspectRatio":"16:9","imageUrls":["https://static.nanophoto.ai/demo/nano-banana-pro.webp"]}]' \
  --resolution 720p \
  --follow

Check status of an existing job#

bash

python3 scripts/veo_3_1.py status \
  --task-ids-json '[{"shotId":"shot-1","taskId":"task_abc123"}]' \
  --resolution 720p

Script behavior#

The bundled script resolves credentials in this order: --api-key, then NANOPHOTO_API_KEY from the environment, then ~/.openclaw/openclaw.json at skills.entries.veo-3-1.env.NANOPHOTO_API_KEY.

Subcommands:

• submit: submit a generation task
• submit --follow: submit and keep polling in the same process
• status: check an existing Veo generation

Cross-platform note:

• Use python3 on macOS/Linux.
• Use python on Windows unless python3 is available.
• The script uses Python's standard HTTP client and does not require curl.
• Use --json-only when another script/tool needs raw JSON output.
• Use --poll-interval to override the default 8-second polling interval.
• Default max wait is 1800 seconds.

Manual API calls#

Submit generation#

bash

curl -X POST "https://nanophoto.ai/api/veo-3/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NANOPHOTO_API_KEY" \
  --data-raw '{
    "shots": [
      {
        "id": "shot-1",
        "prompt": "A golden retriever running on a beach at sunset, cinematic lighting",
        "generationType": "TEXT_2_VIDEO",
        "aspectRatio": "16:9"
      }
    ],
    "resolution": "720p"
  }'

Check status#

bash

curl -X POST "https://nanophoto.ai/api/veo-3/check-status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NANOPHOTO_API_KEY" \
  --data-raw '{
    "taskIds": [
      {"shotId": "shot-1", "taskId": "task_abc123"}
    ],
    "resolution": "720p"
  }'

Error handling#

errorCodeCauseActionLOGIN_REQUIREDInvalid or missing API keyVerify key at https://nanophoto.ai/settings/apikeysAPI_KEY_RATE_LIMIT_EXCEEDEDRate limit exceededWait and retryINSUFFICIENT_CREDITSNot enough creditsTop up creditsSHOTS_REQUIREDMissing shots arrayBuild a valid shots payloadPROMPT_REQUIREDMissing prompt in a shotAdd prompts to every shotINVALID_IMAGE_COUNTWrong image count for generation typeFix imageUrls for that shot typeIMAGE_URLS_REQUIREDAPI needs public image URLsDo not send local files or base64GENERATION_FAILEDServer-side generation errorRetry or simplify the shot promptsTASK_IDS_REQUIREDMissing task IDsPass valid {shotId, taskId} pairsTASK_NOT_FOUNDTask not found or not owned by callerRe-submit or verify ownershipINTERNAL_ERRORServer-side failureRetry later

Bundled files#

• scripts/veo_3_1.py: single entry point for submit, status, and optional in-process polling
• references/api.md: condensed API reference, shot rules, and error behavior