Uploads and references

Media references

Every field that takes media (image, mask, reference_images, start_image, end_image, reference_audios, source_video) accepts any of these:

Uploading once and reusing the upl_ id is faster than sending the same URL again and again.

Uploading a file

• POST/v1/uploadsUpload a file (multipart) or import one from a URL (JSON). Needs the uploads scope.
• GET/v1/uploads/{id}Read an upload and its moderation status.

Send multipart/form-data with the file in a field named file, and optionally a project_id field. Videos must name a project_id. It answers 201 Created with the upload.

curl -X POST "https://rogue-api.sentryq-va.com/v1/uploads" \
  -H "Authorization: Bearer $ROGUE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@portrait.jpg"

Importing from a URL

Send JSON with a public https URL instead of a file. We download it (following up to 3 redirects, for up to 30 seconds) and upload it for you. URLs with credentials or pointing at private networks are refused.

curl -X POST "https://rogue-api.sentryq-va.com/v1/uploads" \
  -H "Authorization: Bearer $ROGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://example.com/photos/portrait.jpg"
}'

The upload object

{
  "id": "upl_01k6g1z8q2w3e4r5t6y7u8i9o0",
  "object": "upload",
  "status": "processing",
  "type": "image",
  "url": "https://cdn.example.com/rogue/uploads/portrait.jpg",
  "file_name": "portrait.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 482113,
  "width": 1024,
  "height": 1536,
  "error": null,
  "created_at": "2026-09-28T11:58:12.004Z"
}

statusstring

processing while Rogue checks the file, then ready or rejected.

typestring

image, video or audio, detected from the file contents.

urlstring

Where the file lives on Rogue.

width, heightinteger | null

Pixel size, for JPEG and PNG images.

errorstring | null

Why a rejected upload was refused.

Formats and limits

The type comes from the file's contents, not its name or declared content type. Anything else, WebP and GIF included, answers 400 invalid_request.

Moderation

Rogue checks uploaded images and videos before they can be used. Audio is ready at once. A new image or video starts as processing and becomes ready or rejected, usually within seconds; the upload.ready and upload.rejected webhooks tell you which.

• You do not have to wait: a generation that references a processing upload waits for it before it starts.
• Referencing a rejected upload answers 422 moderation_blocked.
• If Rogue has not answered within 45 seconds, the upload is treated as ready.

Masks for inpainting

An inpaint mask is a PNG the same size as the image: white marks what to change, black what to keep. Send it inline as a data URL, or upload it first and pass its upl_ id.

"mask": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."

Library and projects

Everything you generate lands in your Rogue library, filed in a project.

• GET/v1/assetsSearch the library: type, project_id, search, favorites, page, limit.
• GET/v1/assets/images/{id}One image from the library.
• PATCH/v1/assets/{type}/{id}Mark or unmark a favorite: {"favorite": true}. Needs library.
• DELETE/v1/assets/{type}/{id}Delete an item from the library. Needs library.
• GET/v1/projectsList projects: page, limit, search.
• POST/v1/projectsCreate a project: {"title": "Spring shoot"}. Needs projects.
• GET/v1/projects/{id}One project.
• PATCH/v1/projects/{id}Rename a project. Needs projects.
• DELETE/v1/projects/{id}Delete a project. Needs projects.

Pagination

Lists answer { "object": "list", "data": [...], "page": 1, "limit": 30, "has_more": true }. Ask for the next page while has_more is true. Library and project pages hold up to 60 items.