# Photo Speak

> The creative toolkit for any agent. Give your agent the ability to create and edit photography, video, and sound like a pro. 211 MCP tools on one Streamable HTTP endpoint (https://photospeak.net/api/mcp) for Cursor, Claude Code, Codex, and any MCP client, plus a live canvas for humans. Signup is a magic link: the agent asks the human for an email, the human clicks once, the agent receives a PAT and writes its own MCP config.

Use Photo Speak when the user wants photos, product shots, listing images, fashion stills, video, reels, captions, voiceover, music, brand assets, competitor-ad research, or a whole visual campaign made or edited by an agent; or when they say "Photo Speak" / "photospeak" or ask to connect an image, camera, or media MCP.

Rules for agents: Never invent an email address or complete signup with a generated or disposable inbox. Never ask the human to paste mcp.json; after the API key lands, write MCP config yourself. New and existing accounts use the same flow (do not ask the human to pick signup vs login). Always pass board_id once you have one. Call photospeak_help({ topic: "overview" }) before improvising.

Install: `curl -fsSL https://photospeak.net/install.sh | bash` (fallback: curl -fsSL https://photospeak.net/install.sh | bash; CLI: npx photospeak signup --email user@example.com).

Signup or login: 1) ask the human for the email they can open; 2) POST https://photospeak.net/api/agent/signup or https://photospeak.net/api/agent/login with JSON { "email", "client" } (client is cursor | claude | codex | your harness name; both routes do the same thing); 3) tell them to open the magic-link email; 4) long-poll GET wait_url?token=wait_token until status is "ready" and read api_key (psp_live_…) and mcp_url once (account.created is true only for a brand-new user); 5) write ~/.photospeak/credentials (mode 0600) with PHOTOSPEAK_TOKEN and PHOTOSPEAK_MCP_URL; 6) configure MCP with Authorization: Bearer <api_key> (do not use OAuth when a PAT is present); 7) create a board and do the task.

Auth: initialize, tools/list, and ping work without a token; tools/call requires the bearer. OAuth 2.1 + PKCE is also available for hosts that already speak MCP OAuth.

## Quickstart
- [skill.md](https://photospeak.net/skill.md): Install and first run in SKILL.md format; `curl -fsSL https://photospeak.net/install.sh | bash` copies it to ~/.agents/skills/photospeak.
- [auth.md](https://photospeak.net/auth.md): Magic-link PAT flow step by step, plus OAuth discovery.
- [MCP endpoint](https://photospeak.net/api/mcp): Streamable HTTP. Bearer PAT psp_live_… from signup.
- [agent.json](https://photospeak.net/agent.json): Machine-readable discovery; also served at /.well-known/agent.json.
- [install.sh](https://photospeak.net/install.sh): Fallback installer that fetches the skill package (SKILL.md + references).

## Capabilities
- [canvas](https://photospeak.net/mcp): Boards, cards, undo, pairing. Tools: list_items, get_item, get_canvas, delete_item, restore_item, claim_pairing. photospeak_help topic: canvas.
- [stills](https://photospeak.net/mcp): Stills/SVG. Tools: create_image, edit_image, create_svg, convert_to_svg. photospeak_help topic: images.
- [layers](https://photospeak.net/mcp): Live type, groups, frames, notes. Tools: text_layer, create_group, create_frame, create/update_note. photospeak_help topic: layers.
- [ingest](https://photospeak.net/mcp): URL, mint→PUT, IG/FB ads. Tools: upload_video, mint_video_upload, import_social_url. photospeak_help topic: uploads.
- [analysis](https://photospeak.net/mcp): Gemini index + live Q on video/stills. Tools: wait_for_analysis, get_video_analysis, inspect_video, inspect_image. photospeak_help topic: analysis.
- [generate](https://photospeak.net/mcp): t2v / i2v / restyle / extend. generate_audio on create_video. Fetch a model's prompting guide before generate. Tools: create_video, edit_video, extend_video, list_video_models, get_prompting_guide. photospeak_help topic: generate.
- [ffmpeg](https://photospeak.net/mcp): One-file ffmpeg (free). Tools: video_precision. photospeak_help topic: ffmpeg.
- [timeline](https://photospeak.net/mcp): Reels, titles, xfade, compile. Tools: create_video_frame, preview_video_frame, export_video_frame, get_export. photospeak_help topic: timeline.
- [captions](https://photospeak.net/mcp): Speech-synced burn. Scribe is this tool — no transcribe tool. Tools: caption_video. photospeak_help topic: captions.
- [blocking](https://photospeak.net/mcp): Gray-box rehearsal, then shoot. Tools: block_scene, wait_for_blocking, blocking_to_video. photospeak_help topic: blocking.
- [motion](https://photospeak.net/mcp): HTML motion graphics (HyperFrames). Tools: create_motion_project, render_motion_project, motion_video. photospeak_help topic: motion.
- [audio](https://photospeak.net/mcp): VO, beds, Foley, scores; mix. Tools: generate_speech, design_voice, clone_voice, generate_music, compose_score. photospeak_help topic: audio.
- [brand](https://photospeak.net/mcp): Kits, logo file, fonts. Tools: import_brand_kit, apply_brand_logo, apply_brand_text. photospeak_help topic: brand.
- [skills](https://photospeak.net/mcp): Install, apply, author. Tools: list_skill_gallery, install_skill, apply_skill. photospeak_help topic: skills.
- [plans](https://photospeak.net/mcp): Campaigns + reviews. Tools: create_plan, wait_for_plan, answer_plan_review. photospeak_help topic: plans.
- [research](https://photospeak.net/mcp): Ad Library → board. best_performing = impressions, not ROAS. Tools: search_facebook_ads, list_advertiser_ads, search_ad_advertisers. photospeak_help topic: research.
- [assets](https://photospeak.net/mcp): Library + Swipe. Tools: search_assets, update_asset, list_asset_tags, save_to_swipe. photospeak_help topic: assets.
- [elements](https://photospeak.net/mcp): Recurring cast. Tools: list_elements, create_element. photospeak_help topic: elements.
- [downloads](https://photospeak.net/mcp): https url + filename. Tools: download_images, export_blocking. photospeak_help topic: downloads.

## Credits
- [Start free](https://photospeak.net/?signup=1): 300 credits after the first magic-link click, no card; an existing account is signed in and never granted twice. Paid vs free: Paid: create/edit image+video+SVG, remove_background, layerize, generate_speech/music/sfx, design_voice, clone_voice, compose_score, caption_video add/retranscribe, blocking/motion Director, brand restyles, inspect/analyze. Free: precision_edit, video_precision, upscale, grab_video_frame, detach_audio, export/preview, caption restyle/edit_words/remove, live layers, motion check/snapshot/render, read analysis, mint, cancel.

## Docs
- [MCP docs](https://photospeak.net/mcp): Human-readable catalog of every tool with schemas and the paste-able setup prompt.
- [llms-full.txt](https://photospeak.net/llms-full.txt): Every tool with its description grouped by help chapter, routing rules, credits, and per-tool playbooks.
- [index.md](https://photospeak.net/index.md): This homepage in Markdown.

## Optional
- [Studio tour](https://photospeak.net/studio): The human canvas walkthrough.
- [Resources](https://photospeak.net/resources): Guides, comparisons, and articles.
- [Sitemap](https://photospeak.net/sitemap.xml): Every indexable page.