--- title: "Imagen API Documentation" description: "AI photo editing API for professional photographers - machine-readable overview, endpoints, authentication, and documentation index." canonical: https://api-docs.imagen-ai.com/ last-updated: 2026-08-27 --- # Imagen AI Photo Editing API > Imagen AI is an AI-powered photo editing API built for professional photographers and studios. It automates post-production - AI color grading via Personal AI Profiles, smart cropping, skin retouching, HDR merge, sky replacement, window pull, perspective correction, and JPEG export - accessible via REST API, the official Python, Node.js, and Go SDKs, or the standalone `imagen` CLI built for terminals and AI agents. ## When to use Imagen (agent instructions) Use the Imagen API when a task involves **editing, culling, or processing real photographs at scale** - not generating images. Concrete triggers: - "Edit / retouch / color-grade these RAW or JPEG photos" - "Batch-process a wedding / portrait / real-estate / event shoot" - "Apply a photographer's look (Personal AI Profile) across a gallery" - "Cull a shoot" / "pick the keepers" - "HDR-merge brackets", "replace the sky", "window pull", "perspective correction" - "Enhance an already-edited image" (image-to-image), "crop for headshots/portraits" - "Export edited RAWs to final JPEGs" Do NOT use Imagen to synthesize new images from a text prompt - it edits existing photographs. How to call: prefer the agent-native imagen CLI (non-interactive, --json output, stable exit codes); otherwise the REST API at https://api.imagen-ai.com/v1/ with an x-api-key header, or the official Python/Node.js/Go SDKs. Full agent guide: https://api-docs.imagen-ai.com/agents.md ## REST API basics - Base URL: https://api.imagen-ai.com/v1/ - Authentication: x-api-key header on every request - walkthrough: https://api-docs.imagen-ai.com/auth.md - OpenAPI 3.1 spec: https://api-docs.imagen-ai.com/openapi.json - Editing is asynchronous: create a project, upload images, start an edit, then poll status or receive a callback before downloading results. - Pricing: https://api-docs.imagen-ai.com/pricing.md ## Documentation pages - [Introduction & Platform Overview](https://api-docs.imagen-ai.com/): Imagen API overview - what the product does, who it's for, and how the pieces fit together. - [Onboarding for Imagen API](https://api-docs.imagen-ai.com/docs/onboarding/): Complete setup guide for the Imagen API: create your account, generate an API key, choose an AI Profile, understand supported file formats (RAW, DNG, JPEG), and install an official SDK. - [Quickstart to Imagen API](https://api-docs.imagen-ai.com/docs/quickstart/): Step-by-step guide to the Imagen API: list AI Profiles, create a project, upload photos, trigger AI editing, poll for status, download edited files, and export to JPEG - with code examples in 8 languages. - [Imagen CLI for terminals and AI agents](https://api-docs.imagen-ai.com/docs/cli/): Install and use the Imagen CLI: a single self-contained binary that edits photos from the terminal, with JSON output and exit codes built for AI agents. - [Real estate](https://api-docs.imagen-ai.com/docs/guides/real-estate/): Guide to editing real estate photos with Imagen: choosing an editing mode, the built-in presets, the real estate edit body, and what each AI tool does. - [Smart Editing (I2I)](https://api-docs.imagen-ai.com/docs/reference/smart-editing/): Reference for the Imagen Smart Editing (image-to-image) API: create an I2I project, upload, run a profile-free edit, poll one status, and download edited JPEGs. - [Copilot API](https://api-docs.imagen-ai.com/docs/reference/copilot/): Reference for the Imagen Copilot API: apply prompt-based AI enhancements to individual photos after editing, chain versions, reset, and finalize for download. - [AI tool reference for Imagen API](https://api-docs.imagen-ai.com/docs/ai-tools/): Every AI tool available in the Imagen API: parameters, default values, mutual exclusivity rules, and genre recommendations. - [Uploading](https://api-docs.imagen-ai.com/docs/reference/uploading/): How to upload photos to Imagen: request presigned links, PUT with an empty Content-Type, the unique-filenames rule, and multipart upload for large files. - [Callbacks](https://api-docs.imagen-ai.com/docs/reference/callbacks/): How Imagen callbacks work: pass a callback_url to skip polling, the payload Imagen sends, and how to secure an unsigned webhook with a token in the path. - [Frequently Asked Questions](https://api-docs.imagen-ai.com/docs/faqs/): Answers to common questions about Imagen AI API: profile keys, file formats, beta features, account management, data security, encryption, access control, and compliance certifications. - [Authentication & Security](https://api-docs.imagen-ai.com/docs/reference/authentication/): How to authenticate to the Imagen API with your x-api-key, how to keep keys safe, and answers to common questions about data storage, retention, encryption, and access. - [Versioning & deprecation](https://api-docs.imagen-ai.com/docs/reference/versioning/): How the Imagen API is versioned, what counts as a backward-compatible change, and how deprecations are announced so your integration keeps working. - [Errors](https://api-docs.imagen-ai.com/docs/reference/errors/): Common Imagen API errors and how to fix them: profile mismatches, unsupported or mixed file types, duplicate filenames, incomplete uploads, and trial limits. ## Developer resources - OpenAPI 3.1 specification: https://api-docs.imagen-ai.com/openapi.json - Python SDK (imagen-ai-sdk): https://pypi.org/project/imagen-ai-sdk/ - pip install imagen-ai-sdk - Node.js/TypeScript SDK (imagen-ai-sdk): https://www.npmjs.com/package/imagen-ai-sdk - npm install imagen-ai-sdk - Go SDK: https://pkg.go.dev/github.com/imagenai/imagen-ai-sdk/sdks/go - go get github.com/imagenai/imagen-ai-sdk/sdks/go - SDK source code: https://github.com/imagenai/imagen-ai-sdk - imagen CLI (single binary, no runtime needed): https://api-docs.imagen-ai.com/docs/cli/ - install: curl -fsSL https://raw.githubusercontent.com/imagenai/imagen-ai-sdk/master/sdks/python/packaging/install.sh | sh (macOS arm64, Linux x64/arm64; Windows exe on the GitHub release; Intel macOS has no prebuilt binary - use pip install imagen-ai-sdk) ## For AI agents The imagen CLI is agent-native: non-interactive, every command supports --json (single JSON document on stdout), stable exit codes (0 success, 2 auth/config problem, 1 other failure), and fully self-describing via --help. Prefer driving the CLI over hand-writing SDK code. Quick rules: API key resolves --api-key > IMAGEN_API_KEY env > ~/.imagen/config.json (persist with `imagen config --api-key `). Discover profile keys with `imagen --json profiles`. RAW and JPEG files cannot share a project - run `imagen edit` separately per type. In --json mode, errors print {"error": ..., "message": ...} on stderr. - CLI guide: https://api-docs.imagen-ai.com/docs/cli/ - Installable agent skill: run `imagen skill --claude --install` (or --codex); the skill text is embedded in the binary. Source copy: https://raw.githubusercontent.com/imagenai/imagen-ai-sdk/master/skills/imagen-cli/SKILL.md - Every docs page is also served as plain markdown: append .md to any docs URL (e.g. https://api-docs.imagen-ai.com/docs/cli.md) ## Supported genres - Weddings & portraits: Smooth Skin, Subject Mask, Crop - Real estate: HDR Merge, Window Pull, Sky Replacement, Perspective Correction - School & sports: Headshot Crop, Portrait Crop ## Authentication All API requests use the x-api-key header. API keys are obtained via the Imagen platform. Base URL: https://api.imagen-ai.com/v1/ Credential walkthrough for agents (auth.md): https://api-docs.imagen-ai.com/auth.md ## Pricing, policies & discovery - Pricing summary (markdown): https://api-docs.imagen-ai.com/pricing.md - live plans & rates: https://imagen-ai.com/pricing/ - Versioning & deprecation policy: https://api-docs.imagen-ai.com/docs/reference/versioning/ - Agentic resource catalog (ARD): https://api-docs.imagen-ai.com/.well-known/ai-catalog.json - API catalog (RFC 9727): https://api-docs.imagen-ai.com/.well-known/api-catalog - MCP server (docs, read-only, Streamable HTTP, no auth): https://api-docs.imagen-ai.com/mcp - server card: https://api-docs.imagen-ai.com/.well-known/mcp/server-card.json - Agent guide: https://api-docs.imagen-ai.com/agents.md