References

Add a reference image

Adds an image as a collection-scoped style reference (up to 6 references). Pass either url to download and store a new reference, or asset_id to copy an existing uploaded/generated image into this collection when needed. The returned reference_asset_ids are always collection-scoped assets that the app can display and future generations can use. Invalidates the cached style_card, which will be re-extracted on next generation. No credit cost.

post/v1/collections/{id}/references

Request

  • Base URL: https://api.masko.ai
  • URL: https://api.masko.ai/v1/collections/{id}/references
  • Auth: HTTP bearer

Path parameters

idstring uuid required

Headers

Idempotency-Keystring

Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.

Request body

asset_idstring uuid

Asset ID of an existing uploaded or generated image. If the asset is not already scoped to this collection, the API creates a collection-scoped reference copy and stores that copied asset ID in reference_asset_ids.

urlstring uri

Public HTTP(S) image URL, up to 10 MB with a 15-second download deadline. Private addresses and unsafe redirects are rejected. PNG, JPEG, WebP, GIF and SVG are supported; SVG is converted to PNG. Downloaded and stored as a collection-scoped reference asset.

Response

Reference added

Changes

No recorded changes to this operation across all 2 revisions of this API.