Server-first SDK
Use @image2url/next to accept files in Route Handlers or API Routes, push them to image2url, and ship CDN-cached links in one call. Built for speed, observability, and zero broken embeds.
Cache strategy
public, max-age=31536000
Validation
MIME + size guard
Formats
URL + Markdown/HTML/BBCode
import { uploadImage } from '@image2url/next';
import { NextResponse } from 'next/server';
export async function POST(request: Request) {
const form = await request.formData();
const file = form.get('file');
if (!(file instanceof File)) {
return NextResponse.json({ error: 'Missing file' }, { status: 400 });
}
const result = await uploadImage({
file,
alt: 'hero-banner',
endpoint: 'https://www.image2url.com/api/upload',
});
return NextResponse.json(result);
}Secure by default
HTTPS uploads, MIME validation, size caps, and filename encoding. Returns structured errors you can log.
SEO-friendly links
Stable CDN URLs with cache headers and alt-friendly usage strings for blogs, docs, and embeds.
Deterministic output
URL plus Markdown, HTML, and BBCode strings, plus filename, mimeType, size, and uploadedAt fields.
Server-first uploads
Keep tokens server-side, stream files in Route Handlers, and avoid leaking credentials to the client.
Observability built in
Consistent JSON for logging and analytics. Add your own retries or telemetry without guessing response shapes.
Edge-friendly fallback
Works in the node runtime and degrades gracefully at the edge. Configure endpoints per environment.
Cache you can trust
Public, long-lived cache headers on outputs. Perfect for docs, marketing sites, and static renders.
Open source roadmap
We ship in the open. Help us add signed URLs, image transforms, and framework presets.
Drop-in migration
Swap your upload helper with a single call; keep your forms and UI untouched.
We are collecting real-world patterns: signed uploads, CDN custom domains, Next.js middleware examples, and DX improvements. Stars, issues, and PRs on GitHub keep the project healthy.
Prefer React hooks? Try @image2url/react. Need agent flows? Use mcp-server-image2url.
What does @image2url/next solve?
It keeps uploads server-side in Next.js (Route Handlers or API Routes), returns typed JSON, and ships CDN-ready URLs with Markdown/HTML snippets.
Do I need API keys?
The default endpoint on image2url.com offers a free IP-based quota. Self-hosted deployments can enforce tokens and custom size limits.
Is it edge compatible?
Yes. The helper runs in Route Handlers and supports streaming bodies. It works best in node runtimes but degrades gracefully.
Can I contribute?
Absolutely. We are building in public at github.com/image2url/image2url-sdk. Issues, PRs, and docs improvements are welcome.
What responses do I get back?
Permanent URL plus filename, mimeType, size, uploadedAt, and formatted strings (Markdown, HTML, BBCode) for instant pasting.
How is reliability handled?
Uploads are HTTPS, validated for MIME and size, set Cache-Control: public, max-age=31536000, and return structured errors you can log.
Ready to ship
CDN-backed URLs, typed responses, and a community-driven roadmap.