# fireimg (Ruby gem)

Server-side Ruby client for API-key uploads, optional moderation, and CDN URLs. It handles the two-step presigned upload (request URLs, then PUT to S3) the same way the FireImg CLI does.

gem 'fireimg', '~> 1.1'

Fireimg.configure do |c|
  c.api_key = ENV.fetch('FIREIMG_API_KEY')
  c.project = ENV.fetch('FIREIMG_PROJECT')
end

result = Fireimg.upload(
  filename: 'hero.jpg',
  content_type: 'image/jpeg',
  path: './hero.jpg'
)
# result.cdn_url => https://img.fireimg.com/your-project/images/hero.jpg

Create an API key under API Keys in the FireImg app. The full secret is shown only once.

# Install

# Gemfile
gem 'fireimg', '~> 1.1'

bundle add fireimg

# Configure

Fireimg.configure do |c|
  c.api_key = ENV.fetch('FIREIMG_API_KEY')
  c.project = ENV.fetch('FIREIMG_PROJECT')
  c.api_base = ENV.fetch('FIREIMG_API_BASE', 'https://api.fireimg.com')
  c.cdn_base = ENV.fetch('FIREIMG_CDN_BASE', 'https://img.fireimg.com')
end

FIREIMG_API_KEY and FIREIMG_PROJECT are also read automatically if you skip the block. Prefer environment variables so the key does not appear in source or process lists.

Staging:

Fireimg.configure do |c|
  c.api_base = 'https://api.fireimg.dev'
  c.cdn_base = 'https://img.fireimg.dev'
end

# Upload

Fireimg.upload requests a presigned URL, then PUTs the bytes:

result = Fireimg.upload(
  filename: 'feed_items/43/uuid.jpg',
  content_type: 'image/jpeg',
  path: '/tmp/photo.jpg', # or io: / body:
  sizes: [
    { width: 800, quality: 'medium', fmt: 'webp' },
    { width: 160, height: 160, fit: 'cover', pos: 'center', fmt: 'webp' }
  ]
)

result.image_key # => "feed_items/43/uuid.jpg"
result.cdn_url   # => "https://img.fireimg.com/{project}/images/feed_items/43/uuid.jpg"

filename may include folders. Provide the bytes with path:, io:, or body:.

Optional sizes (up to 20) are generated asynchronously after the PUT and replace the project's default image params for that upload. Omit sizes to keep project defaults. Pass sizes: [] to pre-generate only FireImg's 80px dashboard thumbnail.

Fireimg.upload_many(files:, sizes:) batches the same way as the CLI (up to 20 files per presign request).

CDN transforms are on-demand after the PUT. The gem does not wait for optimization jobs.

If the client PUTs directly (mobile or browser), use Fireimg.presign and PUT to result.upload_url with the same Content-Type. See the API reference for the HTTP contract.

# Moderate and delete

labels = Fireimg.moderate('feed_items/43/uuid.jpg')
Fireimg.delete('feed_items/43/uuid.jpg')

Moderation returns FireImg labels; your app applies policy. See the API reference for the response shape.

# URLs

Fireimg.public_url('feed_items/43/uuid.jpg')
# => https://img.fireimg.com/{project}/images/feed_items/43/uuid.jpg

Fireimg.url('feed_items/43/uuid.jpg', width: 800, quality: 'medium', fmt: 'webp')
# => …/images/feed_items/43/uuid.jpg?width=800&quality=medium&fmt=webp

Supported options match the Image URL reference: width, height, quality, fmt / format, fit, pos / position, and fill.

# CLI

For uploads from a terminal, CI job, or coding agent, use the FireImg CLI instead.