Shortodellashortodella

API

Access Shortodella AI generation, screenshots, and search via API. All endpoints require an API key.

API Keys

Endpoints

All endpoints require Authorization: Bearer sk_... header

POST/v1/runAI agent — natural language commands
POST/v1/generate/imageGenerate image from prompt (+ reference_images)
POST/v1/generate/images/batchBatch image generation — 50% off, ≤24h SLA (Nano Banana NIGHT)
POST/v1/generate/videoGenerate video (+ source_image, end_image)
GET/v1/tasks/:task_idPoll async task status
POST/v1/site-tools/trimOpen browser video trim editor
POST/v1/site-tools/cropOpen browser image crop editor
POST/v1/site-tools/listShow user a grid of assets
POST/v1/site-tools/pickAsk user to pick from a set
POST/v1/site-tools/swipeTinder-style keep / discard
GET/v1/site-tools/sessions/:idPoll site-tool session result
POST/v1/assets/uploadUpload your own image / video
GET/v1/assetsList your assets
GET/v1/assets/searchSearch public library
GET/v1/assets/:uidGet asset details
POST/v1/screenshot/websiteScreenshot a website
POST/v1/extract/brandExtract brand style
POST/v1/describeDescribe image with AI
POST/v1/merge/videosMerge video assets
GET/v1/energyCheck energy balance
GET/v1/modelsList available models
GET/v1/aboutAPI info for AI agents

Run

General-purpose AI agent. Send a natural language command and get text + generated assets back.

POST https://api.shortodella.com/v1/run

Parameters

promptNatural language command (required)
imagesAsset UIDs to attach as context
image_modelnanobanana (default) | grok | gpt-image-1.5 | gpt-image-2
video_modelkling (default) | grok | veo
size1024x1024 (default)

Response (202)

{ "task_id": "task_abc123", "status": "processing", "poll_url": "/api/v1/tasks/task_abc123" }

Example

curl -X POST "https://api.shortodella.com/v1/run" \ -H "Authorization: Bearer sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "generate a logo for a coffee shop called Bean & Brew"}'

Poll result

{ "task_id": "task_abc123", "status": "completed", "result": { "message": "I've generated a logo for Bean & Brew.", "assets": [ { "uid": "png_xyz", "type": "png", "url": "https://...", "width": 1024, "height": 1024 } ] } }

Generate

Generate AI images and videos from text prompts. Images are synchronous, videos are async.

Image

POST https://api.shortodella.com/v1/generate/image

Parameters

promptText prompt (required)
modelnanobanana (default) | grok | gpt-image-1.5 | gpt-image-2
size1024x1024 | 1248x832 | 832x1248
reference_imagesUp to 3 asset uids — img-to-img / editing / consistency

Response

{ "asset_uid": "png_a1b2c3", "status": "completed", "url": "https://...", "width": 1024, "height": 1024 }

Example

curl -X POST "https://api.shortodella.com/v1/generate/image" \ -H "Authorization: Bearer sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Keep the cat and pose. Change the sign text to NEKO COFFEE.", "model": "nanobanana", "reference_images": ["png_base123"] }'

Image batch (NIGHT — 50% off)

Async — submits a Nano Banana 2 batch job (Gemini Batch API). Costs 0.5 energy per image (50% of sync). SLA up to 24h, no realtime guarantee — only use it when you can wait. Returns a task_id; poll /v1/tasks/:task_id.

POST https://api.shortodella.com/v1/generate/images/batch

Parameters

itemsArray (1-100) of { prompt, size?, reference_images? }
items[].promptText prompt (required)
items[].size1024x1024 (default) | 1248x832 | 832x1248
items[].reference_imagesUp to 3 asset uids — img-to-img / editing
webhook_urlOptional HTTPS URL to be notified on completion

Response (202)

{ "task_id": "task_abc123", "status": "processing", "poll_url": "/api/v1/tasks/task_abc123", "estimated_seconds": 3600, "item_count": 10, "energy_cost": 5.0 }

Poll result

{ "task_id": "task_abc123", "status": "completed", "progress": 100, "result": { "succeeded": 9, "failed": 1, "items": [ { "index": 0, "status": "completed", "asset_uid": "png_xxx", "url": "https://...", "width": 1024, "height": 1024 }, { "index": 1, "status": "failed", "error": "blocked: SAFETY" } ] } }

Example

curl -X POST "https://api.shortodella.com/v1/generate/images/batch" \ -H "Authorization: Bearer sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "prompt": "anthropomorphic cat barista, soft morning light", "size": "832x1248" }, { "prompt": "anthropomorphic cat in leather jacket, neon alley", "size": "832x1248" } ] }'

Failed items refund 0.5 energy each automatically. Whole-batch failure refunds the full amount.

Video

Async — returns a task_id. Poll /v1/tasks/:task_id until complete.

POST https://api.shortodella.com/v1/generate/video

Parameters

promptText prompt (required)
modelgrok | kling (default) | veo | seedance
duration3-15 seconds (seedance: 4-15)
aspect_ratio16:9 (default) | 9:16 | 1:1 | 4:3 | 3:4
source_imageAsset uid — start frame for image-to-video
end_imageAsset uid — end frame (kling / seedance only; with source_image)

Response (202)

{ "task_id": "task_xyz789", "status": "processing", "poll_url": "/api/v1/tasks/task_xyz789", "estimated_seconds": 120 }

Check status

GET https://api.shortodella.com/v1/tasks/:task_id

Poll every 3-5 seconds until status is completed or failed.

{ "task_id": "task_xyz789", "status": "completed", "progress": 100, "result": { "asset_uid": "video_abc", "url": "https://...", "width": 1920, "height": 1080, "duration": 5 } }

Site Tools

Browser interfaces driven from the API. The endpoint returns a tool_url that the user opens in their logged-in browser. After they finish, the result is created as a new asset (edit tools) or returned via session polling (choice tools). Energy: free.

Edit tools — single asset → new asset

POST /v1/site-tools/trimBody: { asset_uid }. Video trim editor. New trimmed video, parent_asset_uid → original.
POST /v1/site-tools/cropBody: { asset_uid }. Image crop editor. New cropped image, parent_asset_uid → original.

Response

{ "tool_url": "https://shortodella.com/site-tools/trim?asset=video_abc123", "asset_uid": "video_abc123", "tool": "trim" }

Choice tools — multi asset → user selection

POST /v1/site-tools/listBody: { asset_uids[], title? }. Read-only grid; no result collected.
POST /v1/site-tools/pickBody: { asset_uids[], min?, max?, title? }. Multi-select → { picked_uids }.
POST /v1/site-tools/swipeBody: { asset_uids[], title? }. Tinder cards → { kept_uids, discarded_uids }.

Response

{ "tool_url": "https://shortodella.com/site-tools/pick?session=sess_xxx", "session_id": "sess_xxx", "poll_url": "/api/v1/site-tools/sessions/sess_xxx", "tool": "pick", "expires_in": 86400 }

Poll the session

GET https://api.shortodella.com/v1/site-tools/sessions/:id

Poll every 2s. status goes from pending → done when the user submits. Sessions live for 24h.

{ "session_id": "sess_xxx", "tool": "pick", "status": "done", "asset_uids": ["png_a", "png_b", "png_c", "png_d"], "result": { "picked_uids": ["png_b", "png_d"] }, "completed_at": 1730000300 }

Example — ask user to pick 2 of 4

curl -X POST "https://api.shortodella.com/v1/site-tools/pick" \ -H "Authorization: Bearer sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "asset_uids": ["png_a","png_b","png_c","png_d"], "min": 2, "max": 2, "title": "Pick 2 covers" }'

Assets

Upload

POST https://api.shortodella.com/v1/assets/upload

Multipart form-data. Allowed: png, jpg, webp, gif, mp4, webm. Max 50MB. Energy: free.

curl -X POST "https://api.shortodella.com/v1/assets/upload" \ -H "Authorization: Bearer sk_YOUR_KEY" \ -F "file=@/path/to/image.png"

List your assets

GET https://api.shortodella.com/v1/assets

typeall (default) | image | video
limit1-100 (default 20)
sortnewest (default) | oldest

Get one

GET https://api.shortodella.com/v1/assets/:uid

Returns asset metadata with a presigned download URL valid for 7 days.

{ "uid": "png_a1b2c3", "title": "Cat in space", "url": "https://...", "width": 1024, "height": 1024, "media_type": "png" }

Screenshots

POST https://api.shortodella.com/v1/screenshot/website

Parameters

urlWebsite URL (required)
viewportdesktop (default) | mobile
count1-5 screenshots (default 1)

Example

curl -X POST "https://api.shortodella.com/v1/screenshot/website" \ -H "Authorization: Bearer sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://stripe.com", "viewport": "desktop"}'

Async — poll /v1/tasks/:task_id for result. Energy cost: 1.

Brand Extraction

POST https://api.shortodella.com/v1/extract/brand

Extracts logo, colors, fonts, and theme from a website. Async — poll for result. Energy cost: 1.

Parameters

urlWebsite URL (required)

Result

{ "success": true, "colors": ["#1a1a2e", "#e94560", "#0f3460"], "fonts": { "heading": "Inter", "body": "Inter" }, "logo": { "type": "svg", "url": "https://..." }, "site_theme": { "is_dark": false } }

Energy Costs

Image (nanobanana / grok)1
Image (gpt-image-1.5)3
Image (gpt-image-2)4
Video (grok, per sec)1
Video (kling, text-to-video, per sec)2
Video (kling, image-to-video, per sec)4
Video (veo, per sec)3
Video (seedance, per sec)3
Screenshot / Brand1
Site Tools (trim/crop/list/pick/swipe)0
Upload / Search / Describe / Merge0

GET https://api.shortodella.com/v1/energy

{ "total": 91.7, "permanent": 91.7, "subscription": 0, "daily_bonus": 0, "subscription_plan": null }

Rate Limits

Free10 req/min
Premium60 req/min
Pro120 req/min