Guides
Image hosting guides for agents and developers.
Use these guides to upload public images, automate screenshots, and choose the correct hosting workflow.
Getting started
-
How to Create a Temporary Image URL and Restore the Same Link
Upload with unpublish_after_hours, confirm the public URL becomes a 404, then publish the hash again to restore the same URL.
-
How to Generate Alt Text During an Image Upload
Upload the image, poll GET /v1/images/:hash for at most 20 attempts, and use alt_text only when the terminal status is live.
-
How to Turn a Screenshot Into a URL From the Command Line
Capture a PNG file, upload it as the multipart file field, and print the returned imgd.dev URL.
-
How to Upload an Image With cURL and Get a Public URL
Send a POST request to https://imgd.dev/v1/upload with the file field, then read the public URL from the JSON response.
Languages
-
Upload an Image With Go
Create a multipart file part with its real image media type, send it with net/http, decode success or error JSON, and verify the result.
-
Upload an Image With JavaScript and Node.js
Read the image with Node.js, append a typed Blob to FormData as file, send it with fetch, and validate HTTP 200 or 202.
-
Upload an Image With PHP cURL
Use PHP CURLFile to post an image as the file form field, then validate the JSON response and public URL.
-
Upload an Image With Python Requests
Open the image in binary mode, send it as the multipart file field with requests, surface the server fix, and verify the result.
-
Upload an Image With Ruby Net HTTP
Use Ruby Net HTTP and set_form to upload an image without an external upload gem.
-
Upload an Image With Rust and reqwest
Use reqwest to send a multipart file field to the imgd.dev upload endpoint and read the public URL from typed JSON.
-
Upload an Image With TypeScript
Model success and API-error JSON, parse the response as unknown, narrow it with type guards, and accept HTTP 200 or 202.
Automation workflows
-
Add Hosted Images to Markdown and README Files
Upload one image, copy its public URL, and insert it with non-empty Markdown alt text in a README.
-
Host Images for HTML Email Without Base64
Upload the image before email delivery, then reference its public URL from an HTML img element instead of embedding base64 data.
-
Host Puppeteer Screenshots on a Public URL
Use Puppeteer Page screenshot with a file path, close the browser in finally, then upload the PNG with Node fetch.
-
How to Let Claude Code, Codex, or Cursor Upload Screenshots
Expose IMGD_KEY through the host environment and give the coding agent a shell script that accepts one image path and prints one public URL.
-
How to Upload Playwright Failure Screenshots From GitHub Actions
Set Playwright screenshots to only-on-failure, guard the upload by failure and file existence, and write the returned URL to GITHUB_STEP_SUMMARY.
-
Post a Hosted CI Screenshot in a GitHub Pull Request Comment
Run untrusted pull request code with a read token, then upload and comment only from a separate trusted job.
-
Resize and Convert a Hosted Image to WebP or AVIF by URL
Add w and fmt query values to one public image URL to request resized WebP, AVIF, JPEG, or PNG output.
-
Store OpenAI-Generated Images on a Stable Public URL
Decode the image_generation_call result from base64, then upload the PNG bytes to imgd.dev for a content-addressed public URL.
-
Upload a Python Chart and Embed It in a Report
Save a fixed Matplotlib chart as PNG, upload it with Requests, then print a public URL with useful report markup.
Choosing a host
-
Image Hosting APIs Without a Subscription
Use imgd.dev for one-time storage, img402 for free or per-image uploads, or a competitor free plan for a limited monthly quota.
-
imgd.dev vs Cloudinary: Simple Agent Uploads or a Full Media Platform?
Choose imgd.dev for a small public-image API with one-time storage. Choose Cloudinary for video, DAM, teams, and broad transformation workflows.
-
imgd.dev vs img402: Reusable Storage or Per-Image Payment?
Choose img402 for no-account free uploads or $0.01 per-image payment. Choose imgd.dev for reusable storage, image management, and content-addressed URLs.
-
Imgur API Alternatives for Automated Screenshots
Imgur has an API and can remain best for its community and account workflows. Choose an alternative when direct automation is the main task.
-
What Is the Best Image Host for AI Agents?
There is no universal best image host for AI agents. Choose imgd.dev for simple paid public storage, or choose a competitor for its specific strength.
Engineering
-
How Actionable API Errors Help AI Agents Recover
Branch on both HTTP status and the stable error code. Show the server fix verbatim, and retry only transient failures.
-
How to Moderate Terminal Screenshots Without Treating Error Text as Violence
Judge what a terminal screenshot depicts, not the words it contains. Require independent confirmation before a destructive moderation action.
-
Image Moderation Thumbnail Size: Cost Versus Readability
imgd.dev uses MODERATION_EDGE_PX = 768 in production. The old 256-pixel setting was cheaper but made a wide screenshot unreadable.
-
Make Image Upload Retries Safe With Content-Addressed URLs
Retry only network failures, HTTP 429, and server failures. Reuse identical bytes so imgd.dev returns the same SHA-256 hash and public URL.
-
Why imgd.dev Serves a Blurred Placeholder During Image Moderation
imgd.dev returns the final public URL immediately, but it does not serve unreviewed recognizable bytes. Processing is temporary; review is terminal.