Files
Upload File
Upload images and videos to Genviral CDN for use in TikTok slideshows, Instagram carousels, YouTube Shorts, Pinterest pins, LinkedIn posts, and Facebook content. Supports programmatic uploads from OpenClaw agents and automation pipelines.
POST
Upload media files directly to Genviral’s storage, then finalize the stored bytes into a
CDN-backed Media Library record. A preparation never creates a visible file by itself.
How It Works
- Call this endpoint with the file’s content type and a stable
Idempotency-Key - Receive a file
idand presigneduploadUrl - Upload your file directly to the
uploadUrlusing a PUT request - Call
POST /api/partner/v1/files/{fileId}/finalizewith the same media metadata and a stableIdempotency-Key - Use the finalized
file.urlin post creation or pack-image attachment requests
Body Parameters
string
required
MIME type of the file. Supported types:
- Images:
image/jpeg,image/png,image/gif,image/webp,image/heic,image/heif - Videos:
video/mp4,video/quicktime,video/x-msvideo,video/webm,video/x-m4v
string
Original filename for reference (optional). Used for display purposes only.
number
Optional video duration in seconds. Also accepts
duration_seconds, duration, durationSec,
or video_duration_sec. Stored with the CDN file record so /posts can hydrate validation
metadata when you use the returned url.number
Optional file size in bytes from 1 through 52,428,800 (50 MB). Also accepts
size.Response
Successful requests return201 with:
uploadUrl- Presigned URL to upload your file (expires in 10 minutes)id- Stable upload identity used by the finalize endpointcontentType- The content type you specifiedexpiresIn- Seconds until the upload URL expires (600)
file, including its verified byte size and public
https://cdn.vireel.io/... URL. Invalid, absent, empty, oversized, or MIME-mismatched bytes are
rejected without creating a Media Library row.
Using With Packs
If your goal is to add a local file to a pack:- Call this endpoint and capture
data.id+data.uploadUrl. - Upload your bytes to
data.uploadUrlwithPUT. - Finalize the upload and capture
data.file.url. - Call Add Pack Image with
image_url = data.file.url.
Examples
Upload a video
Error Responses
400 invalid_request-Idempotency-Keyis missing or invalid400 invalid_json- Request body is not valid JSON422 invalid_payload- Invalid content type or missing required fields401- authentication failed (missing/invalid/revoked token)402 subscription_required- active Creator/Professional/Business plan required403 tier_not_allowed- Scheduler tier cannot use Partner API500 create_failed- Failed to initialize upload (retry)
The presigned upload URL expires after 10 minutes. If it expires before you upload,
simply request a new one.
