createGeneration
Each accepted POST durably records a separate generation. While pending_funding the reserved amount is zero. Funding success queues the job; check its status for a funding rejection. Submitting the same request twice can incur two charges. After a lost response, check the generation list before deciding to create another task.
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.
| Field | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| inputobjectRequired | Generation parameters. The fields depend on the model and operation; see the model page. Fields of input
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| metadatamap<string, string>Optional | Your own string values, returned unchanged. Put client_reference here so a lost response can be matched later. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| modelstringRequired | Model ID from listModels or the model page. At least 1 characters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| operationstringRequired | What to generate. Only operations published for the model are accepted. text-to-videoimage-to-videoreference-to-videovideo-editvideo-extendvideo-draftdraft-to-videogenerate-imagegenerate-audioclone-voicegenerate-videoprocess-video | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| quote_idstringOptional | At least 1 characters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| routingobjectOptional | Pin a specific route. Without it the platform picks the published route for the model. Fields of routing
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| webhook_endpoint_idstringOptional | Webhook endpoint to notify when the task changes state. Create endpoints in the console. |
Responses
202 Accepted
| Field | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| allowed_actionsstring[], can be nullRequired | Actions you can take now, such as cancel. Rely on this list instead of inferring from the status. | ||||||||||||||||||||||||||||||
| billing_statusstringRequired | Whether Credits are held, charged or released. | ||||||||||||||||||||||||||||||
| closed_atdate-time, can be nullRequired | When the task closed. Stop polling once it is not null. | ||||||||||||||||||||||||||||||
| customer_resolution_deadlinedate-timeRequired | Twenty-four hours after acceptance. Holds still unsettled at this time are released. | ||||||||||||||||||||||||||||||
| delivery_statusstringRequired | Whether the result is stored and downloadable. ready means it can be downloaded. | ||||||||||||||||||||||||||||||
| errorobject, can be nullRequired | Set when the task closed without a result. Read error.code. Fields of error
| ||||||||||||||||||||||||||||||
| execution_statusstringRequired | Progress of the model run. | ||||||||||||||||||||||||||||||
| idstringRequired | Resource ID. Save it as soon as you receive it. | ||||||||||||||||||||||||||||||
| late_result_availablebooleanRequired | A result that arrived after closing is provided at no charge. | ||||||||||||||||||||||||||||||
| metadatamap<string, string>Optional | Your own string values, returned unchanged. Put client_reference here so a lost response can be matched later. | ||||||||||||||||||||||||||||||
| priceobjectRequired | Credits for this task: quoted (the price when it was accepted), reserved and charged. charged stays 0.000 until settlement. Fields of price
| ||||||||||||||||||||||||||||||
| resultobject, can be nullRequired | Delivered assets, once available. Fields of result
| ||||||||||||||||||||||||||||||
| statusstringRequired | Overall state of the task. | ||||||||||||||||||||||||||||||
| versionintegerRequired |
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
|
| 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. |
| 402 | Available Credits cannot cover this request. Add Credits, wait for them to be credited, then check the balance. |
| 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. |
| 429 | Too many requests. No task was created. Wait for the Retry-After time before sending again. |
| 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. |
| Timeout or disconnect | No response, or the connection dropped. The task may be accepted. With a task ID, read that task; without one, find it by client_reference in the task list. |
Request example
cURL
curl -X POST "https://api.vizoapi.com/v1/generations" \
-H "Authorization: Bearer $VIZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_FROM_PROJECT",
"operation": "text-to-video",
"input": {
"prompt": "A paper boat drifting on a pond",
"duration_seconds": 5
}
}'Python
import os, requests
res = requests.post(
"https://api.vizoapi.com/v1/generations",
headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
json={
"model": "MODEL_FROM_PROJECT",
"operation": "text-to-video",
"input": {
"prompt": "A paper boat drifting on a pond",
"duration_seconds": 5
}
},
timeout=60,
)
print(res.status_code, res.json())Node.js
const res = await fetch("https://api.vizoapi.com/v1/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "MODEL_FROM_PROJECT",
"operation": "text-to-video",
"input": {
"prompt": "A paper boat drifting on a pond",
"duration_seconds": 5
}
}),
});
console.log(res.status, await res.json());Response 202
{
"allowed_actions": [
"cancel"
],
"billing_status": "held",
"closed_at": null,
"customer_resolution_deadline": "2026-11-03T08:00:12Z",
"delivery_status": "pending",
"error": null,
"execution_status": "queued",
"id": "gen_01JD8Z5QW3XR",
"late_result_available": false,
"metadata": {
"client_reference": "order-1042"
},
"price": {
"charged": "0.000",
"price_version": "p3",
"quoted": "1400.000",
"reserved": "1400.000",
"unit": "credit"
},
"result": null,
"status": "queued",
"version": 1
}Response 401
{
"error": {
"code": "invalid_credentials",
"message": "API key is missing, malformed, expired or revoked.",
"retryable": false,
"request_id": "9f2c41d07ab3e5c8"
}
}Response 402
{
"error": {
"code": "insufficient_balance",
"message": "Available credits cannot cover the hold.",
"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 429
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Check Retry-After.",
"retryable": true,
"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"
}
}