Generate images and video with an OpenClaw agent

An agent building a product page needs a finished image file before it can use that image. The API Stock media skill handles the asynchronous task: discover parameters, quote the request, create it once and retrieve its terminal result. It also supports music requests from the live catalog.

Download the skill and examples. For installation and credentials, start with OpenClaw setup.

Choose a first task

The archive's examples/ directory contains the task briefs and JSON requests. These examples stay local. Sending posts or publishing a page is a separate action that needs the user's instruction.

Quote the exact request

From the extracted bundle directory, check the selected model's current inputSchema. Use camelCase public input fields.

python3 skills/api-stock-media/scripts/api_stock.py catalog --model nano-banana-2.1
python3 skills/api-stock-media/scripts/api_stock.py estimate \
  --request examples/product-page/image-request.json

For API Hubs, put --site apihubs before each command. The quote returns costMicroUsd in millionths of USD and costUsd in USD. It does not create a task. A trial may not cover the selected request. Current pricing is on the pricing page; the authenticated quote includes your price.

Approve a ceiling and create once

Use a ceiling covering this specific request. The value below is an example of an authorized limit, not a promise that every image costs that amount:

python3 skills/api-stock-media/scripts/api_stock.py run \
  --request examples/product-page/image-request.json \
  --state product-image-task.json \
  --max-cost-usd 0.05 --confirm-paid --timeout 60

The helper checks the quote and sends a server-enforced maximum charge. Before sending the creation request, it saves an idempotency key. That state file belongs to one logical generation. The agent's LLM token spend is separate from this media ceiling.

Recover after a timeout

Keep the JSON request and state file. Run the same command again. A lost creation response is recovered with the same key, so uncertainty does not require a second paid task. Do not generate a new key just to retry a connection. If a killed process left a .lock, verify it has stopped before removing only the lock; preserve the state JSON.

Once the task id is known, polling is read-only:

python3 skills/api-stock-media/scripts/api_stock.py wait TASK_ID --timeout 60

waiting means the local deadline ended while the remote task may still run. failed and expired are terminal and require a deliberate decision before a new generation. Stopping the helper does not cancel a remote task. Failed generations follow the API's refund policy; a polling timeout is not itself a refundable failure.

Use the result in the artifact

This image was generated during a live check on 2 November 2026. OpenClaw 2026.10.9 used GPT 6 Luna to call the media helper. The first agent attempt selected an invalid execution host; a second attempt with explicit tool arguments created one image task and received its finished result. Four LLM requests were used across the two attempts. This is one observed run, not a model-quality or reliability benchmark.

The exact image prompt was:

A single orange paper lantern on a midnight blue studio background, folded paper texture, soft side light, generous empty space around the lantern, editorial product illustration, no text, no logos

The original request used the unsupported aspectRatio field. The server ignored it and used its default size: "16:9". The current recipe names size explicitly; the image above is the original output.

The acceptance account is a service account with no user-balance debit. That is not a public free-generation offer; ordinary accounts use the current authenticated quote and their prepaid balance. The local validation harness assembled the demonstration page from this result; the run does not establish autonomous website-building quality.

After finished, read files[].fileUrl and output. Some catalog actions return structured data without files. Download media using a separate request without the API bearer key, then reference the local file in the page or draft. Report the model, task id, terminal status and estimate. Record an actual charged amount only when it has been observed.

The product-page recipe saves an HTML page and evidence.json. The content-kit recipe saves draft text and separate records for its cover and optional video. Both report failed or missing assets instead of presenting fixture output as a successful generation.

Read task status, error handling and model selection for agents before expanding to longer automated runs.