createAssetUpload

POST/v1/assets/uploads

Markdown fileTry in PlaygroundDocs version r15

Authentication

Send your project key in the request header, for example Authorization: Bearer $VIZO_API_KEY. Keep the key on your server.

Request body

A JSON object. Fields that are not listed are rejected.

Request body
Field	Description
max_bytesintegerRequired	Largest file size you will upload, in bytes. Minimum 1, Maximum 20000000
mimestringRequired	Media type of the file you will upload. `image/pngimage/jpegimage/webpvideo/mp4audio/mpegaudio/wav`

Responses

200 OK

200 OK
Field	Description
asset_idstringRequired	ID of an uploaded or delivered asset.
upload_urlstringRequired	Upload the file bytes to this URL, then call completeAssetUpload.
url_expires_atdate-timeRequired	When the URL stops working. Ask again for the same asset.

Errors

Errors share one body. Include the request_id when you contact support.

Error body

Field

Description

errorobjectRequired

Details of the error.

Fields of error

Fields of error
codestringRequired	Stable error code to branch on.
messagestringRequired	Readable explanation. Do not parse it.
request_idstringRequired	Include this when you contact support.
retryablebooleanRequired	True for 429 and 503 only. Even then, check recent tasks before you send a create request again.
task_idstringOptional	The task this error belongs to, when one exists.

Errors
Status	What it means and what to do
401	The key is missing, malformed, expired or revoked. Correct the key on your server, then continue.
403	The key scope, email verification, a budget or an account restriction blocks this. Check the key type, scopes and project budget.
404	The model or resource does not exist or is outside this project. Check the project, the ID and that the model is enabled.
409	The request conflicts with the current state. Read the resource again and decide whether to send the request again.
422	A field or value is invalid. Compare the request with the field table and the model page.
500	The server failed and the task may already be accepted. Do not resend; list recent tasks first.
503	The service is temporarily unavailable. For a create request, list recent tasks and confirm none was accepted before you submit again.

Request example

cURL

curl -X POST "https://api.vizoapi.com/v1/assets/uploads" \
  -H "Authorization: Bearer $VIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_bytes": 20000000,
    "mime": "video/mp4"
  }'

Python

import os, requests

res = requests.post(
    "https://api.vizoapi.com/v1/assets/uploads",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    json={
      "max_bytes": 20000000,
      "mime": "video/mp4"
    },
    timeout=60,
)
print(res.status_code, res.json())

Node.js

const res = await fetch("https://api.vizoapi.com/v1/assets/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "max_bytes": 20000000,
    "mime": "video/mp4"
  }),
});
console.log(res.status, await res.json());

Response 200

{
  "asset_id": "ast_01JD8Z9M2C4V",
  "upload_url": "https://media.vizoapi.com/u/ast_01JD8Z9M2C4V?sig=…",
  "url_expires_at": "2026-11-02T08:16:43Z"
}

Response 401

{
  "error": {
    "code": "invalid_credentials",
    "message": "API key is missing, malformed, expired or revoked.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

Response 403

{
  "error": {
    "code": "scope_denied",
    "message": "The key does not allow this operation for this project.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

Response 404

{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is not available to this project.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

Response 409

{
  "error": {
    "code": "conflict",
    "message": "The request conflicts with the current state of the resource.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

Response 422

{
  "error": {
    "code": "invalid_input",
    "message": "Input does not match the published schema.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

Response 500

{
  "error": {
    "code": "request_failed",
    "message": "The request failed. Check recent generations before submitting again.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

Response 503

{
  "error": {
    "code": "temporarily_unavailable",
    "message": "Service is temporarily unavailable.",
    "retryable": true,
    "request_id": "9f2c41d07ab3e5c8"
  }
}