POST /v1/evaluations
Starts an evaluation of one or more assets against the frameworks you name.
Multipart, not JSON — the assets can travel in the same request. Repeat the frameworkIds and files fields to send more than one. You supply the assets exactly one way per request: inline, from the upload flow, from assets already in the workspace, or from urls Voxly Vision fetches. Each of the four is shown below. The work is queued: the response returns as soon as it is accepted, and each asset becomes its own job. Limits are 5 assets and 3 frameworks per request, 500 MB per file.
Parameters
- namestringrequired
- Labels the batch in the workspace.
- frameworkIdsuuid[]required
- One field per framework the assets are judged against, 3 at most. Get the ids from GET /v1/frameworks.GET /v1/frameworks →
- filesfile[]optional
- The assets themselves. One field per file, 5 per request, 500 MB each.Content types →
- uploadIdsuuid[]optional
- Instead of files. Ids from POST /v1/uploads whose bytes you already sent to storage; the evaluation completes the upload for you.POST /v1/uploads →
- assetIdsuuid[]optional
- Instead of files. Re-runs assets already in the workspace; nothing is uploaded and they keep their folder.GET /v1/assets →
- fileUrlsstring[]optional
- Instead of files. Public https urls Voxly Vision downloads itself — http is refused, as are private, loopback and link-local addresses. 500 MB per file, 8192 characters per url.
- labelIduuidoptional
- Files newly created assets into a folder. Ignored for assetIds re-runs, which keep the folder they already have.
- idempotencyKeyuuidoptional
- Reusing one returns the original batch instead of running — and charging — twice.
5 ways to call this
Send the file with the request
The simplest form. The asset is uploaded and evaluated in one call.
curl -X POST "https://api.voxlyvision.com/api/v1/evaluations" \
-H "X-API-Key: $VOXLY_API_KEY" \
-F name="Spring campaign" \
-F frameworkIds="550e8400-e29b-41d4-a716-446655440000" \
-F files=@hero.pngUse an upload you already sent
For large media. Request an upload url, PUT the bytes to storage, then name the uploadId here — the evaluation turns it into an asset for you, so the completion call is not needed.
curl -X POST "https://api.voxlyvision.com/api/v1/evaluations" \
-H "X-API-Key: $VOXLY_API_KEY" \
-F name="Spring campaign" \
-F frameworkIds="550e8400-e29b-41d4-a716-446655440000" \
-F uploadIds="e41b8d6a-2c95-4f38-90b7-3a5d6e2f7c18"Re-run an asset already in the workspace
Nothing is uploaded. Use this to judge existing media against a new framework, or against a newer version of the same one.
curl -X POST "https://api.voxlyvision.com/api/v1/evaluations" \
-H "X-API-Key: $VOXLY_API_KEY" \
-F name="Portman v3 re-run" \
-F frameworkIds="550e8400-e29b-41d4-a716-446655440000" \
-F assetIds="3c9a1b70-52d8-4e11-bb7f-6d2c8a4f1e93"Have us fetch the file from a url
For assets that already live somewhere public — a CDN, a signed link from your DAM. https only, and internal addresses are refused.
curl -X POST "https://api.voxlyvision.com/api/v1/evaluations" \
-H "X-API-Key: $VOXLY_API_KEY" \
-F name="Spring campaign" \
-F frameworkIds="550e8400-e29b-41d4-a716-446655440000" \
-F fileUrls="https://cdn.example.com/spring/hero.png"File into a folder safely
A destination folder and an idempotency key so a retry cannot charge twice.
curl -X POST "https://api.voxlyvision.com/api/v1/evaluations" \
-H "X-API-Key: $VOXLY_API_KEY" \
-F name="Spring campaign" \
-F frameworkIds="550e8400-e29b-41d4-a716-446655440000" \
-F files=@hero.png \
-F labelId="7b2e9c04-1f83-4a55-9d61-0c8e3b5a2f47" \
-F idempotencyKey="9f14c8a2-6d30-4b7e-8a51-2e9c4f0b6d83"{
"evaluationId": "6b21f8ad-3f4e-4c7a-9f10-2b8d5c1e04a7",
"status": "pending",
"jobs": [
{
"id": "b7d4c2f1-90ae-4d63-8c25-1a6f7e930bd4",
"status": "pending",
"assetId": "3c9a1b70-52d8-4e11-bb7f-6d2c8a4f1e93",
"assetName": "spring-campaign-hero.jpg"
}
]
}