Skip to content
Docs version r15
OpenAPIJSONYAML
API reference / Generations

createGeneration

POST/v1/generations

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.

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
FieldDescription
inputobjectRequired

Generation parameters. The fields depend on the model and operation; see the model page.

Fields of input
Fields of input
aspect_ratiostringOptional
asset_idstringOptional
At most 128 characters
duration_secondsintegerOptional
Minimum -1
generate_audiobooleanOptional
nativeanyOptional
promptstringOptional
At least 1 characters, At most 4000 characters
resolutionstringOptional
source_generation_idstringOptional
At most 128 characters
videoobjectOptional
Fields of video
Fields of video
bitrate_modestringOptional
contentobject[], can be nullOptional
Fields of content
Fields of content
asset_idstringOptional
draft_generation_idstringOptional
rolestringOptional
textstringOptional
typestringRequired
urlstringOptional
draftbooleanOptional
execution_expires_afterintegerOptional
moderation_optionsobjectOptional
Fields of moderation_options
Fields of moderation_options
ipsstring[], can be nullRequired
omni_reference_task_typestringOptional
output_formatstringOptional
return_last_framebooleanOptional
safety_identifierstringOptional
seedintegerOptional
toolsobject[], can be nullOptional
Fields of tools
Fields of tools
typestringRequired
watermarkbooleanOptional
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
Fields of routing
modestringRequired
pinned
routestringRequired
At least 1 characters
webhook_endpoint_idstringOptional

Webhook endpoint to notify when the task changes state. Create endpoints in the console.

Responses

202 Accepted

202 Accepted
FieldDescription
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
Fields of error
codestringRequired

Why the task closed without a result, for example insufficient_balance, budget_exceeded or spending_blocked.

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
Fields of price
chargedstringRequired
price_versionstringRequired
quotedstringRequired
reservedstringRequired
unitstringRequired
credit
resultobject, can be nullRequired

Delivered assets, once available.

Fields of result
Fields of result
asset_idstringOptional
last_frame_asset_idstringOptional
metadataobjectOptional
Fields of metadata
Fields of metadata
durationintegerOptional
framesintegerOptional
framespersecondintegerOptional
generate_audiobooleanOptional
ratiostringOptional
resolutionstringOptional
seedintegerOptional
outputsobject[], can be nullOptional
Fields of outputs
Fields of outputs
asset_idstringRequired
content_typestringRequired
indexintegerRequired
voice_idstringOptional
statusstringRequired

Overall state of the task.

versionintegerRequired

Errors

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

Error body

Error body
FieldDescription
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
StatusWhat 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"
  }
}