POST · /api/v1/generate

Submit a generation.

Kicks off a generation against the chosen model with your prompt and any model-specific params. Returns a generation_id immediately — actual rendering runs async; poll the status endpoint to read the result.

Request

POST /api/v1/generate HTTP/1.1
Host: getvivix.com
Authorization: Bearer vvx_live_…
Content-Type: application/json

{
  "model":         "grok-imagine-image-quality",
  "prompt":        "a misty forest at dawn, cinematic 24mm",
  "aspect_ratio":  "16:9",
  "resolution":    "2K"
}

Body params

FieldTypeRequiredNotes
modelstringyesThe slug from /docs/api/models. Must be in your account's allowlist.
promptstringyes*Up to 2000 chars. UTF-8. *Required on models that need one — a text/image-driven model, not one that only takes media inputs.
aspect_ratioenumnoThis model's own aspect-ratio list — the set differs per model (some offer 4, some offer a dozen). See this model's entry under GET /api/v1/models for the exact values.
sizestringnoImage only — exact "WIDTHxHEIGHT" (e.g. "1536x1024"), one of this model's own published sizes. An off-list value is rejected, not snapped to the nearest.
qualityenumnoA tier from this model's own quality enum where it has one (e.g. low / medium / high). Rejected on models with no quality tiers.
resolutionenumnoImage: "1K" / "2K" / "4K". Video: "720p" / "1080p" / "2160p". Each model has its own subset — not every model reaches every tier.
durationintegernoVideo / audio only. Seconds. Range varies by model — typically 2–10.
audiobooleannoSome video models can emit a synced audio track. Defaults to false.
input_imagestring (URL)noPublic https URL, or the id of one of your own completed generations. On a video model this is the first frame (image-to-video); on an image model it's an extra reference for image-to-image.
input_videostring (URL)noSource/driving clip for video-edit, video-to-video, or extend modes — URL or one of your own generation ids. Rejected on models that bill this mode by the clip's exact length, since the API can't measure it.
input_audiostring (URL)noDriving audio track for lipsync / audio-to-video modes.
reference_imagesstring[]noURLs of reference images for img-to-img / style transfer. Up to 3.
seedintegernoPin RNG for deterministic outputs. Same seed + same params = same result.
number_resultsintegernoImage only — request multiple variations in one call. Cost multiplies. Max varies by model.
enhancebooleanno"Enhance" prompt-fitting pass, flat 20 credits on top of credits_estimate, refunded automatically if the fit fails. Only on models where enhance_supported is true in GET /api/v1/models.
estimatebooleannoWhen true, runs the same validation and pricing as a real submit and returns the exact cost — nothing is charged or dispatched. Quote calls have their own per-tier rate limit, double your submit limit, tracked separately so quoting never eats into your real generation budget.
The exact list of accepted params per model comes from GET /api/v1/models. Each model returns a paramsschema you can render forms against — that's the source of truth.

Response

HTTP/1.1 202 Accepted
X-Request-Id: req_a1b2c3d4e5f6

{
  "generation_id":    "5b91a581-ee19-4f86-9fea-bd29471d69d5",
  "status":           "pending",
  "model":            "grok-imagine-image-quality",
  "credits_estimate": 211,
  "pricing_source":   "catalog_default",
  "created_at":       "2026-05-10T12:34:56Z",
  "request_id":       "req_a1b2c3d4e5f6"
}

credits_estimate is the upper bound for the call — it does not include enhance's flat 20 credits, which is billed separately in the background after this response. The final charge — credits_used on the status response — is computed from the final params and any per-customer pricing overrides on your account. pricing_source tells you which layer priced it: "user_override" (a rule on your account), "global_dynamic" (the shared pricing table), or "catalog_default" (the model's base rate — most requests land here).

Errors

Common errors — see the full error reference:

  • 401 AUTH_MISSING — no Authorization header sent at all
  • 401 KEY_INVALID — the key sent doesn't match a live key on your account
  • 402 INSUFFICIENT_CREDITS — not enough balance for this call
  • 403 MODEL_NOT_ALLOWED — your account isn't enabled for that model
  • 422 MISSING_PROMPT — this model needs a prompt and none was sent
  • 422 INVALID_BODY — a param is wrong (out of range, malformed, unparseable JSON, etc.) — most causes name the field under details.field
  • 429 RATE_LIMIT / 429 CONCURRENCY_LIMIT — back off and retry

Where to next