Restory
Try Free
Back to Blog
AI Agents

Inside the Restory AI Agent Stack: API, CLI, Skill, and Media URLs for Visual Production

A practical agent-stack guide for Restory API keys, capabilities discovery, CLI commands, queued media jobs, polling, and CDN result URLs.

MT

Mark Tate

AI Video & Image Specialist

June 11, 2026
12 min read

Share

Inside the Restory AI Agent Stack: API, CLI, Skill, and Media URLs for Visual Production

Inside the Restory AI Agent Stack: API, CLI, Skill, and Media URLs for Visual Production

Direct answer: the Restory AI agent setup is a JSON-first media automation stack. An agent discovers available models, checks credits, uploads local references when needed, submits image or video jobs, polls until completion, and returns stable Bunny CDN result URLs for the next tool in the chain.

This is the practical version of an AI media backend for agents. Codex, Claude, ChatGPT, Cursor, workflow runners, and custom MCP servers do not need to guess which buttons to click. They can read the docs, call discovery endpoints, run the CLI, and hand completed media URLs to publishing tools, ad builders, CMS systems, or social schedulers.

Last verified: June 11, 2026. Use /api/agent/capabilities as the current source of truth for models, settings, variants, feature IDs, and credit costs.

The Stack in One View

Layer What it gives the agent Primary URL or command
Agent docs Human and agent-readable implementation guidance /agent/docs
Markdown docs Short prompt context for LLM agents /api/agent/docs/markdown
Capabilities JSON Current models, restoration methods, settings, variants, and credits /api/agent/capabilities
OpenAPI JSON Schema for API clients, agent tools, and generated SDKs /api/agent/openapi
CLI Local file workflows with structured JSON output npm install -g @restory/cli
Skill file Codex-style instructions for discovery, credits, polling, and handoff skills/restory-agent/SKILL.md
Result URLs Completed media that downstream agents can reuse resultUrl on completed jobs

Why This Works Better Than Browser Automation

Media creation workflows become fragile when an agent has to move through a visual interface: upload fields change, buttons move, hidden progress states fail, and one timeout can make the whole run ambiguous. Restory's agent stack gives the model a stable machine interface instead.

The important design choice is that each step returns structured data. Discovery returns a capability tree. Credit checks return plan and balance data. Generation endpoints return queued job IDs. Polling returns status and final URLs. The CLI prints JSON. That means an agent can plan, execute, verify, and recover without scraping UI text.

The Setup, Step by Step

1. Create an Agent API Key

Open /agent while signed in and create a key for the agent, environment, or worker. Restory API keys use the rst_ prefix and are available on Pro and Ultra plans with AI Agent API Access.

In an agent sandbox or CI runner, store the key as an environment variable:

export RESTORY_API_KEY="rst_..."
export RESTORY_BASE_URL="https://www.restory.pics"

Do not put API keys in prompts, blog comments, public repos, or user-facing logs. The agent should reference the variable and avoid printing the secret.

2. Install the CLI for Local Files

The CLI is the fastest path when an agent starts with files on disk. It uploads local references when needed and returns JSON that can be parsed directly.

npm install -g @restory/cli
restory auth:set --api-key rst_...
restory capabilities
restory credits

Use the public docs first if the agent does not have a key yet. Discovery at /api/agent/capabilities is public so agents can understand the available workflows before authentication.

3. Discover Capabilities Before Choosing Settings

Do not hard-code model settings when an agent can discover them. Restory exposes restoration methods, image generation models, video generation models, accepted settings, feature IDs, and credit costs.

restory capabilities
restory credits

For direct API clients:

GET /api/agent/capabilities
GET /api/agent/credits
Authorization: Bearer rst_...

This matters for video models like Seedance 2.0 where duration, resolution, variant, audio, and reference media options can differ by route.

4. Submit a Media Job

Restory supports agent-controlled photo restoration, image generation, image editing, and video generation. For a simple generated ad image:

restory image:generate \
  --prompt "clean ecommerce hero image for a skincare serum, white tile bathroom, morning light" \
  --model nano-banana-2 \
  --resolution 2K \
  --aspect-ratio 4:5

For image-to-video using a local file:

restory video:generate \
  --prompt "slow cinematic push in, soft daylight, premium product launch feel" \
  --model seedance-2-0 \
  --variant fast-image \
  --image ./product-render.png \
  --duration 8 \
  --resolution 720p

The agent should capture the returned image or video record ID and use that ID for polling.

5. Poll Until Completion

Generation is queued by design. Agents should never assume a job completed synchronously.

restory jobs:get <imageRecordId> --type image
restory jobs:get <videoRecordId> --type video

For API clients:

GET /api/agent/jobs/{id}?type=image
GET /api/agent/jobs/{id}?type=video
Authorization: Bearer rst_...

Completed jobs expose a resultUrl. That URL is the handoff point. It can go into Postiz, a CMS, a landing page builder, an ad creative folder, an email builder, or another media step.

6. Collect Recent Outputs from the Gallery

Batch agents often need to recover from interruptions or collect the latest finished assets. Use the gallery endpoint instead of asking a model to remember file paths.

restory gallery:list --type image --status completed --limit 20
restory gallery:list --type video --status completed --limit 20
GET /api/agent/gallery?type=image&status=completed&limit=20
GET /api/agent/gallery?type=video&status=completed&limit=20

A Copy-Paste Agent Prompt

Use this prompt in Codex, Claude, ChatGPT, or any agent runner that can call shell commands or HTTP tools:

Use Restory as the media generation backend. First read https://www.restory.pics/api/agent/capabilities and https://www.restory.pics/api/agent/openapi. Use RESTORY_API_KEY from the environment. Check credits before batch work. Submit image or video jobs, poll until completed, and return only completed Bunny CDN result URLs plus a short summary of settings used. Do not expose API keys.

Recommended Agent Control Loop

  1. Read agent markdown docs for context.
  2. Call capabilities JSON to discover current model settings.
  3. Call restory credits or GET /api/agent/credits before a batch.
  4. Submit one small test job before scaling to dozens of assets.
  5. Poll jobs until status is completed or failed.
  6. Use completed resultUrl values in the next tool.
  7. Store prompt, model, settings, record ID, status, and result URL in your run log.

Where This Stack Fits

The first use case is social media production. A content agent can generate daily images, restore old archive photos, animate a product still into a video, and hand final URLs to a scheduler.

The second use case is paid creative. A growth agent can create ten product ad angles, generate matching visuals, create a few Seedance video variants, and pass only approved assets to Meta, TikTok, or a review board.

The third use case is documentation and coding agents. Restory exposes markdown docs, OpenAPI JSON, public capabilities, and a skill file, so the agent has multiple surfaces it can read before acting.

FAQ: Restory AI Agent Stack

What is the Restory AI Agent API?

It is a JSON-first API and CLI surface for photo restoration, image generation, image editing, video generation, uploads, credit checks, queued jobs, and result polling.

Can Codex or Claude use Restory?

Yes. Agents can read the markdown docs, use the CLI, call the OpenAPI endpoints, or follow the Restory skill instructions.

Why does the agent need capabilities discovery?

Discovery prevents stale assumptions about models, settings, variants, durations, resolutions, credit costs, and endpoint paths.

Do free users get API keys?

No. API-key authenticated agent workflows require AI Agent API Access on Pro or Ultra plans. Public discovery remains available without a key.

What should an agent return after a job finishes?

Return the completed resultUrl, the record ID, the model/settings used, and any failure notes. Do not return API keys or raw secrets.

Conclusion

The core idea is simple: give agents stable interfaces instead of brittle UI paths. Restory now exposes the surfaces an AI agent needs to create media reliably: public discovery, OpenAPI, markdown docs, CLI commands, skill instructions, credit checks, queued jobs, polling, gallery access, and CDN result URLs.

Start here: Restory Agent Docs
Machine discovery: Capabilities JSON
API schema: OpenAPI JSON
Create keys: /agent
Plan access: Restory pricing

Sources and References

View all articles