{
  "name": "app-video",
  "title": "App API - Video Generation & Understanding",
  "description": "Video generation and understanding for deployed apps (Gipity Video): generate short AI videos, analyze video content",
  "guid": "sk_plat_avid",
  "category": "App services",
  "requiredTools": [
    "project_settings"
  ],
  "content": "# App API - Video Generation & Understanding\n\n## Video Generation (Veo 3.1)\n\nGenerate short AI videos (up to 8 seconds) with audio using Google Veo.\n\n> **Plan availability:** Video generation is **Pro-only** - blocked on the Free plan: a Free-plan owner calling this endpoint gets **403 FORBIDDEN** with an upgrade message. Don't build a Free-tier app around it. (Video *understanding* below is not gated.)\n\n> **Text-to-video only - NOT image-to-video.** This service takes a *prompt* and generates a fresh clip; it cannot animate a *specific image the user uploaded* (there is no image-input parameter). If the app is \"upload a photo and bring it to life\" / \"animate this picture\" / any image-conditioned motion, this is **not** the tool - the generated clip would be an unrelated scene, not the user's photo. Run an image-to-video model (LTX-Video, Stable Video Diffusion) as a **GPU job** instead: the photo is the conditioning frame and the job returns a clip of that exact image moving. See the [jobs](jobs.md) skill (\"Image-to-video\" shape).\n\n### Models\nveo-3.1-generate-preview (best quality, up to 4K, ~$0.40/sec), veo-3.1-fast-generate-preview (faster, ~$0.10/sec), veo-3.1-lite-generate-preview (budget, ~$0.05/sec)\n\n### From the CLI: `gipity generate video`\n```bash\ngipity generate video \"A bird flying over a mountain lake at sunset, slow camera pan\" \\\n  --model veo-3.1-generate-preview --aspect 16:9 --resolution 1080p -o src/assets/lake.mp4\n```\n\nOptions:\n- the prompt (required): describe scene, action, camera movement, dialogue\n- `--model`: see models above (default: veo-3.1-generate-preview)\n- `--aspect`: 16:9 (landscape, default), 9:16 (portrait/vertical), 1:1 (square)\n- `--resolution`: 720p (default), 1080p, 4k\n- `--duration`: clip length: 4, 6, or 8 seconds (8 required at 1080p/4K). Default: 8. Shorter clips cost proportionally less.\n- `-o`: output path; write into `src/` for a clip your app ships\n\nGeneration takes 30-120 seconds. Videos include AI-generated audio.\n\n**Pricing:** billed per second of video produced (provider rate + 5%), so both model and duration matter. A default 8-second clip costs roughly 3360 credits on `veo-3.1-generate-preview`, 840 on `veo-3.1-fast-generate-preview`, and 420 on `veo-3.1-lite-generate-preview`; a 4-second clip costs half that. Prefer shorter clips and the fast/lite models unless the app really needs top visual quality.\n\n### App API Endpoint\n`POST /api/<PROJECT_GUID>/services/video`\n\nRequest:\n```json\n{\n  \"prompt\": \"Close-up of coffee being poured into a cup\",\n  \"model\": \"veo-3.1-fast-generate-preview\",\n  \"aspect_ratio\": \"1:1\"\n}\n```\n\nResponse:\n```json\n{\n  \"url\": \"https://media.gipity.ai/med_abc12345.mp4\",\n  \"content_type\": \"video/mp4\",\n  \"model\": \"veo-3.1-fast-generate-preview\",\n  \"provider\": \"gemini\",\n  \"size_bytes\": 2048000,\n  \"credits_used\": 840\n}\n```\n\n### CLI\nWrites to `./generated.mp4` by default - pass `-o <path>` to land the clip in your source tree so it deploys.\n```bash\ngipity generate video \"a cat playing piano\" --model veo-3.1-fast-generate-preview -o src/assets/video/cat.mp4\ngipity generate video \"vertical dance\" --aspect 9:16 --resolution 1080p -o src/assets/video/dance.mp4\n```\n\n### Tips\n- Be specific: describe lighting, camera angle, movement, and mood\n- Include dialogue in quotes for Veo to generate matching speech\n- 9:16 for social media / mobile content\n- veo-3.1-lite is good enough for previews and iterations\n\n## Video Understanding\n\nAnalyze video content using Gemini's multimodal AI.\n\n### Agent Tool: `video_understand`\n```json\n{\n  \"path\": \"video.mp4\",\n  \"prompt\": \"Describe what happens in this video\"\n}\n```\n\nParameters:\n- `path` (required): Path to video file in workspace\n- `prompt` (required): What to analyze - describe, count, transcribe, summarize, etc.\n\nSupports: mp4, mov, avi, mkv, webm (up to 100MB). Uses Gemini 2.5 Flash.\n\n### Example Prompts\n- \"Describe what happens in each scene\"\n- \"Count the number of people visible\"\n- \"Transcribe all dialogue and text on screen\"\n- \"What brand logos appear in this video?\"\n- \"Summarize the key points of this presentation\""
}