Asset library and asset:// references
Upload media, then use asset://<id> in supported image-generation and video-task fields; handling depends on the model and endpoint.
Upload flow
Create an upload from the console "Asset library" page or through the console API: POST /api/v1/assets returns a pre-signed URL → the browser / client PUTs straight to object storage → POST /api/v1/assets/uploads/{upload_id}/complete runs verification. Assets belong to the current user and are invisible to other users.
The website reference picker accepts original JPG, PNG, or WebP files up to 100 MiB; those over 10 MiB are optimized in the browser before upload. Text/vision chat also accepts originals up to 100 MiB and optimizes them for the inline request; large GIFs use one still frame. Image-generation asset references remain limited to 10 MiB per image and 20 MiB combined. SDK and direct API calls do not optimize originals on the caller's behalf. Video uploads allow up to 200 MiB; other limits are shown in the console.
Referencing in requests
{"type": "image_url", "image_url": {"url": "asset://1024"}, "role": "reference_image"}- For image generations, the gateway checks ownership, bytes and format, then converts the owned asset to Base64 instead of sending LINK42's private asset:// ID upstream. Video tasks use an upstream asset library or direct image input according to account capabilities.
- Which assets a key may reference depends on its asset access; see "Key asset access" on the Authentication, rate limits and idempotency page.
Managing assets with an API key
POST/v1/assets
Server-side code can upload and manage assets through the gateway's /v1/assets endpoints with an API key. They authenticate like model calls (Authorization: Bearer or the x-api-key header), check the key's status and IP allowlist, and do not accept a browser session. The assets methods of the official SDKs wrap these endpoints.
Uploading takes three steps. POST /v1/assets reserves the upload and returns asset (status pending), upload_id and upload. Before upload.expires_at (15 minutes by default), PUT the file to upload.url with every header from upload.headers exactly as given and without your LINK42 key. Then POST /v1/assets/uploads/{upload_id}/complete: the platform checks the file's size, type and actual content, the asset becomes active, and the reference in the response (asset://<id>) can be used in requests.
A reservation may carry an Idempotency-Key header; repeating the same key returns the first reservation with Idempotency-Replayed: true. The asset endpoints allow 120 requests per account per minute (or the key's RPM limit if that is lower); beyond that they answer 429 rate_limited with Retry-After.
| Endpoint | What it does |
|---|---|
| POST /v1/assets | Reserves an upload and answers 201. Body: name (1-160 characters), type (image / video / audio), content_type (must match type) and size_bytes (the file size in bytes). The size limit per file depends on the type and your group; a larger file answers 422 asset_too_large. |
| PUT upload.url | Sends the file straight to storage, with the headers from upload.headers and without your LINK42 key. |
| POST /v1/assets/uploads/{upload_id}/complete | Confirms the upload and returns the active asset. A file not uploaded yet answers 409 asset_object_missing, an expired reservation 409 asset_upload_expired, a size or type that differs from the reservation 422 asset_object_mismatch, and content that is not the declared type 422 asset_content_mismatch. |
| GET /v1/assets | Lists assets, newest first. Query: page, page_size (100 by default, at most 200), type, status (pending / active / failed) and q (matches part of the name, at most 100 characters). Returns {list, total, page, page_size}. |
| GET /v1/assets/{id} | Reads one asset. |
| GET /v1/assets/{id}/download | Returns {url}, a download link valid for 5 minutes, for active assets only. Do not store or share the link. |
| DELETE /v1/assets/{id} | Deletes the asset and answers 204. An asset still referenced by a task answers 409 asset_in_use. |
| Field | Type | Description |
|---|---|---|
| id | integer | Asset ID. |
| name | string | Asset name. |
| type | string | image, video or audio. |
| status | string | pending (waiting for the upload or its confirmation), active (ready to use) or failed. |
| content_type | string | MIME type of the file, for example image/png. |
| size_bytes | integer | File size in bytes. |
| ref_count | integer | Number of tasks that reference the asset; it cannot be deleted while this is above 0. |
| reference | string | asset://<id>, used to reference the asset in a request. |
| created_at | string | When the asset was created. |
| ready_at | string | When the upload was confirmed; null until then. |
curl https://www.link42.ai/v1/assets \
-H "Authorization: Bearer $LINK42_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "reference.png", "type": "image", "content_type": "image/png", "size_bytes": 482913}'
# PUT the file to the returned upload.url; both headers come from upload.headers, no LINK42 key
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/png" \
-H "x-amz-meta-onerelay-upload-id: $UPLOAD_ID" \
--data-binary @reference.png
# Confirm the upload; the reference in the response is asset://<id>
curl -X POST https://www.link42.ai/v1/assets/uploads/$UPLOAD_ID/complete \
-H "Authorization: Bearer $LINK42_API_KEY"How asset access applies to the asset endpoints
A key's asset access also decides which assets it can see and change through /v1/assets. An asset uploaded through these endpoints is recorded against the key that uploaded it; an asset uploaded in the console belongs to no key.
| Operation | own | all | none |
|---|---|---|---|
| Reserve an upload | Allowed | Allowed | 403 asset_access_denied |
| complete | Only uploads this key reserved; any other answers 404 | Any upload in the account | 403 asset_access_denied |
| List, read, download | Assets this key uploaded and assets uploaded in the console; other keys' uploads are left out of the list and answer 404 by id | Every asset in the account | 403 asset_access_denied |
| Delete | Only assets this key uploaded; a console upload answers 403 asset_not_deletable, another key's upload 404 | Every asset in the account | 403 asset_access_denied |
- Every asset an own key cannot see answers 404, exactly like an asset that does not exist, so the key cannot find out what other keys uploaded.
- Console uploads belong to the account itself: an own key can read, download and reference them, but they are deleted in the console or with a key whose asset access is all.