How-to
Upload an image
Create an upload intent, send bytes, and complete the asset safely.
Run this flow in trusted server code when using a private API key.
1. Create an intent
const intent = await client.createUpload({
filename: 'portrait.webp',
contentType: 'image/webp',
size: bytes.byteLength,
visibility: 'public',
galleryIds: ['gallery_id'],
});2. Upload the exact bytes
const response = await fetch(intent.uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': intent.contentType ?? 'image/webp' },
body: bytes,
});
if (!response.ok) throw new Error(`Upload failed: ${response.status}`);3. Complete the intent
const asset = await client.completeUpload(intent.intentId);Completion confirms the object with the API. A successful storage upload alone does not make the asset available in a gallery. Retry completion for the same intent after transient failures.
Browser uploads
Never expose a private API key to create upload intents from the browser. Have your server create a short-lived intent, then return only the bounded upload information needed by the client.