{"id":14971185,"url":"https://github.com/tychenjiajun/exif-ai","last_synced_at":"2025-10-26T14:31:17.781Z","repository":{"id":255440169,"uuid":"850220726","full_name":"tychenjiajun/exif-ai","owner":"tychenjiajun","description":"A Node.js CLI and library that uses OpenAI, Ollama, ZhipuAI, Google Gemini or Coze to write AI-generated image descriptions and/or tags to EXIF metadata by its content.","archived":false,"fork":false,"pushed_at":"2025-02-09T12:39:42.000Z","size":15538,"stargazers_count":12,"open_issues_count":8,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-09T13:33:33.305Z","etag":null,"topics":["ai","cli","cli-tool","coze","exif","gemini","image","jpeg","jpg","llm","metadata","mllm","ollama","openai","openai-api","photo","zhipu"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tychenjiajun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-31T07:18:29.000Z","updated_at":"2025-02-06T05:39:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"0ade8c40-dabf-41c8-bac6-0ad308460c9f","html_url":"https://github.com/tychenjiajun/exif-ai","commit_stats":{"total_commits":93,"total_committers":2,"mean_commits":46.5,"dds":0.4838709677419355,"last_synced_commit":"b68e809c35eb0f0f7eceeff95a737f065acf29cf"},"previous_names":["tychenjiajun/exif-ai"],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tychenjiajun%2Fexif-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tychenjiajun%2Fexif-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tychenjiajun%2Fexif-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tychenjiajun%2Fexif-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tychenjiajun","download_url":"https://codeload.github.com/tychenjiajun/exif-ai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238347625,"owners_count":19456967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","cli-tool","coze","exif","gemini","image","jpeg","jpg","llm","metadata","mllm","ollama","openai","openai-api","photo","zhipu"],"created_at":"2024-09-24T13:44:49.845Z","updated_at":"2025-10-26T14:31:17.770Z","avatar_url":"https://github.com/tychenjiajun.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Exif AI\n\n[![NPM Downloads](https://img.shields.io/npm/dw/exif-ai)](https://www.npmjs.com/package/exif-ai)\n\nhttps://github.com/user-attachments/assets/a445d46a-0d3c-44a2-a42e-f98c23e9c1b4\n\n_Read this in other languages:_\n[_简体中文_](README.zh-CN.md)\n\n## About\n\n_Exif AI_ is a powerful CLI tool and library designed to write AI-generated image descriptions and/or tags directly into the metadata of image files. This tool leverages advanced AI models from multiple providers to analyze image content and generate descriptive metadata, enhancing the accessibility and searchability of your images.\n\nBuilt with the [Vercel AI SDK](https://sdk.vercel.ai/), Exif AI supports 13+ AI providers including OpenAI, Google Gemini, Anthropic Claude, Mistral, Ollama, Amazon Bedrock, Azure OpenAI, and more.\n\n## Quick Start\n\n### CLI Usage\n\nThe CLI has been redesigned for better usability with intuitive commands and clear help text.\n\n#### Basic Usage\n\n```bash\n# Without installation (using npx)\nnpx exif-ai image.jpg --provider ollama\n\n# With global installation\nexif-ai image.jpg --provider ollama\n```\n\n#### Common Examples\n\n```bash\n# Basic usage with Ollama (local, no API key needed)\nexif-ai photo.jpg --provider ollama\n\n# Use OpenAI with specific model\nexif-ai photo.jpg --provider openai --model gpt-4o\n\n# Generate only descriptions\nexif-ai photo.jpg --provider google --tasks description\n\n# Preview without writing to file\nexif-ai photo.jpg --provider anthropic --dry-run\n\n# Verbose output for debugging\nexif-ai photo.jpg --provider ollama --verbose\n```\n\n#### Options\n\nRequired options:\n\n- `-a, --api-provider \u003cvalue\u003e`: Name of the AI provider to use. Supported providers: `openai`, `google`, `anthropic`, `mistral`, `ollama`, `amazon`, `bedrock`, `azure`, `deepinfra`, `fireworks`, `openai-compatible`, `together`, `togetherai`, `xai`, `openrouter`.\n\nOptional options:\n\n- `-T, --tasks \u003ctasks...\u003e`: List of tasks to perform (`description`, `tag`). Default: `['description', 'tag']`.\n- `-i, --input \u003cfile\u003e`: Path to the input image file (required).\n- `-p, --description-prompt \u003ctext\u003e`: Custom prompt for the AI provider to generate description.\n- `--tag-prompt \u003ctext\u003e`: Custom prompt for the AI provider to generate tags.\n- `-m, --model \u003cname\u003e`: Specify the AI model to use, if supported by the provider.\n- `-t, --description-tags \u003ctags...\u003e`: List of EXIF tags to write the description to. Default: `['XPComment', 'Description', 'ImageDescription', 'Caption-Abstract']`.\n- `--tag-tags \u003ctags...\u003e`: List of EXIF tags to write the tags to. Default: `['Subject', 'TagsList', 'Keywords']`.\n- `-v, --verbose`: Enable verbose output for debugging.\n- `-d, --dry-run`: Preview AI-generated content without writing to the image file.\n- `--exif-tool-write-args \u003cargs...\u003e`: Additional ExifTool arguments for writing metadata.\n- `--provider-args \u003cargs...\u003e`: Additional arguments for the AI provider.\n- `--avoid-overwrite`: Avoid overwriting if EXIF tags already exist in the file.\n- `--repeat \u003cnumber\u003e`: Number of times to repeat the task if the AI-generated result is deemed unacceptable. Default: 0.\n\nExample usage:\n\n```bash\n# Legacy CLI syntax (still supported)\nexif-ai -i example.jpg -a ollama\n\n# New improved CLI syntax\nexif-ai example.jpg --provider ollama\nexif-ai example.jpg --provider openai --model gpt-4o\nexif-ai example.jpg --provider google --tasks description --dry-run\n```\n\n### Library Usage\n\nExif AI provides three ways to use it as a library, from simple to advanced:\n\n#### 1. Simple API (Recommended for most use cases)\n\n```typescript\nimport { processImage } from \"exif-ai\";\n\n// Basic usage\nawait processImage({\n  image: \"photo.jpg\",\n  provider: \"ollama\",\n  preview: true // Don't write to file, just preview\n});\n\n// With custom options\nawait processImage({\n  image: \"photo.jpg\",\n  provider: \"openai\",\n  model: \"gpt-4o\",\n  tasks: [\"description\"],\n  descriptionPrompt: \"Describe this image in detail.\",\n  verbose: true\n});\n```\n\n#### 2. Fluent Builder API (For more control)\n\n```typescript\nimport { ExifAI } from \"exif-ai\";\n\nawait new ExifAI(\"photo.jpg\")\n  .provider(\"google\")\n  .model(\"gemini-1.5-pro\")\n  .tasks(\"description\", \"tag\")\n  .descriptionPrompt(\"Describe this landscape photo.\")\n  .tagPrompt(\"Generate relevant tags.\")\n  .preview() // Don't write to file\n  .verbose()\n  .run();\n```\n\n#### 3. Advanced Configuration API (For complex scenarios)\n\n```typescript\nimport { processImageAdvanced } from \"exif-ai\";\n\nawait processImageAdvanced({\n  image: \"photo.jpg\",\n  ai: {\n    provider: \"anthropic\",\n    model: \"claude-3-5-sonnet-20241022\",\n    descriptionPrompt: \"Professional image description\",\n    tagPrompt: \"Generate SEO-friendly tags\"\n  },\n  exif: {\n    descriptionTags: [\"XPComment\", \"Description\"],\n    tagTags: [\"Subject\", \"Keywords\"]\n  },\n  options: {\n    tasks: [\"description\", \"tag\"],\n    preview: true,\n    verbose: true,\n    retries: 2\n  }\n});\n```\n\n#### 4. Legacy API (Backward compatibility)\n\n```typescript\nimport { execute } from \"exif-ai\";\n\nawait execute({\n  path: \"photo.jpg\",\n  provider: \"ollama\",\n  tasks: [\"description\", \"tag\"],\n  dry: true // preview mode\n});\n```\n\n## API Design Benefits\n\nThe new API design provides several improvements:\n\n### CLI Improvements\n- **Intuitive syntax**: `exif-ai image.jpg --provider ollama` instead of cryptic flags\n- **Clear help text**: Organized options with examples and descriptions\n- **Better defaults**: Sensible defaults for common use cases\n- **Grouped options**: Related options are grouped together in help\n- **Backward compatibility**: Old CLI syntax still works\n\n### Library Improvements\n- **Multiple API styles**: Choose the style that fits your use case\n- **Type safety**: Full TypeScript support with proper interfaces\n- **Fluent interface**: Chain methods for readable code\n- **Simple defaults**: Easy to get started with minimal configuration\n- **Advanced control**: Full control when needed\n\n### Developer Experience\n- **Better error messages**: Clear, actionable error messages\n- **Consistent naming**: No more mixed conventions\n- **Modern patterns**: Uses latest JavaScript/TypeScript patterns\n- **Easy testing**: Preview mode for safe testing\n\n## Installation\n\nTo install Exif AI globally, use the following command:\n\n```bash\nnpm install -g exif-ai\n```\n\n## Tasks\n\n### Description\n\nThe `description` task generates a description of the image using the AI provider. The description is written to the specified EXIF tags defined in `descriptionTags`.\n\n### Tag\n\nThe `tag` task generates tags for the image using the AI provider. The tags are written to the specified EXIF tags defined in `tagTags`.\n\n### Note\n\nPlease ensure that you securely manage your API keys. Do not expose them in public repositories or other public forums.\n\n## AI SDK Integration\n\nExif AI is built with the [Vercel AI SDK](https://sdk.vercel.ai/) to provide a unified, modern interface for multiple AI providers. This integration offers:\n\n- **Consistent API**: Same interface across all providers\n- **Better Performance**: Optimized image processing and API efficiency\n- **Type Safety**: Full TypeScript support with proper type definitions\n- **Easy Extensibility**: Simple to add new providers and models\n- **Modern Patterns**: Uses latest AI SDK features and best practices\n\n### Supported Providers\n\n| Provider | Default Model | Description |\n|----------|---------------|-------------|\n| **OpenAI** | `gpt-4o` | Leading AI provider with GPT-4o, GPT-4 Turbo, and other vision models |\n| **Google** | `gemini-1.5-pro` | Google's Gemini models with excellent vision capabilities |\n| **Anthropic** | `claude-3-5-sonnet-20241022` | Claude 3.5 Sonnet and other Claude models with strong reasoning |\n| **Mistral** | `mistral-large-latest` | High-performance European AI models |\n| **Ollama** | `llama3.2-vision` | Local AI models running on your machine (privacy-focused) |\n| **Amazon Bedrock** | `anthropic.claude-3-sonnet-20240229-v1:0` | AWS managed AI service with multiple model choices |\n| **Azure OpenAI** | `gpt-4-vision` | Microsoft's cloud service with OpenAI models |\n| **DeepInfra** | `cogvlm2-llama3-8b-chat` | Platform for open-source and proprietary models |\n| **Fireworks** | `accounts/fireworks/models/llama-v3-8b-instruct` | Fast and cost-effective model inference |\n| **OpenAI Compatible** | `gpt-4-vision` | Generic interface for OpenAI API-compatible services |\n| **TogetherAI** | `cogvlm2-llama3-8b-chat` | Access to wide range of open-source models |\n| **XAI** | `grok-1.5-vision` | Grok models with advanced vision capabilities |\n| **OpenRouter** | `openai/gpt-4o` | Unified gateway to multiple AI providers |\n\n## Configuration\n\n### OpenAI\n\nTo use [OpenAI](https://openai.com/), you need to set the API key. You can do this by setting an environment variable:\n\n```bash\nexport OPENAI_API_KEY=your_openai_api_key\n```\n\nIf you wish to use a custom API service provider that is compatible with the OpenAI API, you can set the `OPENAI_BASE_URL` environment variable to point to the desired endpoint.\n\n```bash\nexport OPENAI_BASE_URL=https://api.customprovider.com/v1\n```\n\n### Google Generative AI\n\nTo use [Google Generative AI](https://ai.google.dev/), you need to set the API key. You can do this by setting an environment variable:\n\n```bash\nexport API_KEY=your_google_api_key\n# or\nexport GOOGLE_API_KEY=your_google_api_key\n```\n\n### Anthropic\n\nTo use [Anthropic](https://www.anthropic.com/), you need to set the API key. You can do this by setting an environment variable:\n\n```bash\nexport ANTHROPIC_API_KEY=your_anthropic_api_key\n```\n\n### Mistral\n\nTo use [Mistral](https://mistral.ai/), you need to set the API key. You can do this by setting an environment variable:\n\n```bash\nexport MISTRAL_API_KEY=your_mistral_api_key\n```\n\n### Ollama\n\nOllama runs locally and does not require an API key. Ensure that Ollama is installed and properly configured on your machine. Refer to the [Ollama GitHub repository](https://github.com/ollama/ollama) for installation and setup instructions.\n\nTo use a remote Ollama service, you can set the base URL using an environment variable:\n\n```bash\nexport OLLAMA_BASE_URL=http://ollama.example.com:11434\n```\n\n### Amazon Bedrock\n\nTo use [Amazon Bedrock](https://aws.amazon.com/bedrock/), you need to set your AWS credentials:\n\n```bash\nexport AWS_ACCESS_KEY_ID=your_aws_access_key_id\nexport AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key\nexport AWS_REGION=us-east-1  # or your preferred region\n```\n\n### Azure OpenAI\n\nTo use [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service/), you need to set the following environment variables:\n\n```bash\nexport AZURE_OPENAI_API_KEY=your_azure_openai_api_key\nexport AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com\nexport AZURE_OPENAI_API_VERSION=2023-12-01-preview  # or your preferred API version\n```\n\n### DeepInfra\n\nTo use [DeepInfra](https://deepinfra.com/), you need to set the API key:\n\n```bash\nexport DEEPINFRA_API_KEY=your_deepinfra_api_key\n```\n\n### Fireworks\n\nTo use [Fireworks](https://fireworks.ai/), you need to set the API key:\n\n```bash\nexport FIREWORKS_API_KEY=your_fireworks_api_key\n```\n\n### OpenAI Compatible\n\nTo use an OpenAI-compatible API service, you need to set the following environment variables:\n\n```bash\nexport OPENAI_COMPATIBLE_API_KEY=your_api_key\nexport OPENAI_COMPATIBLE_BASE_URL=https://api.compatible-service.com/v1\n```\n\n### TogetherAI\n\nTo use [TogetherAI](https://www.together.ai/), you need to set the API key:\n\n```bash\nexport TOGETHER_API_KEY=your_together_api_key\n```\n\n### XAI\n\nTo use [XAI](https://x.ai/), you need to set the API key:\n\n```bash\nexport XAI_API_KEY=your_xai_api_key\n```\n\n### OpenRouter\n\nTo use [OpenRouter](https://openrouter.ai/), you need to set the API key:\n\n```bash\nexport OPENROUTER_API_KEY=your_openrouter_api_key\n```\n\n## Develop\n\n### Prerequisites\n\n- Node.js \u003e=16\n- pnpm\n\n### Clone the Repository\n\nFirst, clone the Exif AI repository to your local machine:\n\n```bash\ngit clone https://github.com/tychenjiajun/exif-ai.git\ncd exif-ai\n```\n\n### Install Dependencies\n\nNext, install the required dependencies using `pnpm`.\n\n```bash\npnpm install\n```\n\n### Build\n\n```bash\npnpm run build\n```\n\n### Watch\n\n```bash\npnpm run watch\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftychenjiajun%2Fexif-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftychenjiajun%2Fexif-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftychenjiajun%2Fexif-ai/lists"}