# createAssetUpload

`createAssetUpload`

`POST /v1/assets/uploads`

## Authentication

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

## Request body

- `max_bytes` (integer, Required) Largest file size you will upload, in bytes. Minimum 1 Maximum 20000000
- `mime` (string, Required) Media type of the file you will upload. Allowed values: `image/png`, `image/jpeg`, `image/webp`, `video/mp4`, `audio/mpeg`, `audio/wav`

```json
{
  "max_bytes": 20000000,
  "mime": "video/mp4"
}
```

## Responses

### 200 OK

- `asset_id` (string, Required) ID of an uploaded or delivered asset.
- `upload_url` (string, Required) Upload the file bytes to this URL, then call completeAssetUpload.
- `url_expires_at` (date-time, Required) When the URL stops working. Ask again for the same asset.

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

### 401 Unauthorized

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

### 403 Forbidden

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

### 404 Not Found

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

### 409 Conflict

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

### 422 Unprocessable Entity

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

### 500 Internal Server Error

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

### 503 Service Unavailable

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

## Errors

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

### Error body

- `error` (object, Required) Details of the error.
  - `code` (string, Required) Stable error code to branch on.
  - `message` (string, Required) Readable explanation. Do not parse it.
  - `request_id` (string, Required) Include this when you contact support.
  - `retryable` (boolean, Required) True for 429 and 503 only. Even then, check recent tasks before you send a create request again.
  - `task_id` (string, Optional) The task this error belongs to, when one exists.

| 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. |

### cURL

```bash
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

```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

```javascript
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());
```