Create a generation task

POST/api/v1/generations

Submits a task and returns immediately. Credits are checked and reserved up front; the response tells you the exact amount.

Request body

Field	Type	Description
`model`	`string` · required	Composite model id from `GET /api/v1/models`, e.g. `"text-to-image:rikcgfbufzdm"`.
`input`	`object` · required	Model parameters, keyed per the model's `params` list — a key that list doesn't have is refused with `invalid_request` (`param` names it). Almost every model takes a `prompt`. Image, video and audio fields take URLs of files stored on this service — upload them first with `POST /api/v1/uploads`, or reuse a previous task's output URL (`GET /api/v1/uploads` lists both); any other URL is refused with `media_not_uploaded`.
`callback_url`	`string`	HTTPS endpoint to POST the task to when it reaches a terminal status. Must not point to a private or internal address.

curl https://vidocraft.com/api/v1/generations \
  -X POST \
  -H "Authorization: Bearer sk_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-to-image:rikcgfbufzdm",
    "callback_url": "https://your-app.com/api/hooks/generation",
    "input": {
      "prompt": "a lighthouse on a cliff at golden hour, cinematic",
      "aspect_ratio": "16:9"
    }
  }'

Response

{
  "taskId": "3f2ak9mr7xqp4tnz8blc6ywh",
  "credits": 1
}

credits is the amount reserved for this task. Test keys additionally return sandbox: true.

Group images (max_images). Some image models take a max_images cap instead of a fixed count: the model returns as many images as the prompt asks for, up to the cap — so state the number in the prompt ("3 images of …"). Credits are reserved for the cap; when the task succeeds, the charge is settled to the images actually returned and the rest is refunded, so the task's credits shows the final amount. Some models cap reference images and max_images together — GET /api/v1/models shows it as sharedLimit on that parameter (e.g. { "with": "image_input", "total": 15 }), and a request over it is refused with invalid_request.
Prompts pass server-side content moderation; rejected prompts return moderation_blocked. So do images and videos linked from an approved domain instead of uploaded.
Image and video results are moderated too. A flagged result is withheld: the task ends failed with failed_reason: nsfw_output_blocked, and its credits are not refunded (billing_status: charged).
Premium models, and any option or param flagged available: false / premium: true in GET /api/v1/models, require an active subscription; otherwise the request fails with 403 forbidden, and for an option or param the error's param names it. Leaving such a param out is fine — it takes the default listed for your account.
Results are private for subscribed accounts and public for free accounts, matching the studio behaviour.

Create a generation task

Request body

Response

On this page