Returns the models your key has access to, with the parameter schema for each (so you can build forms / validate inputs without hard-coding) plus the credit cost band. New models you unlock with us appear here without any code change on your side.
GET /api/v1/models HTTP/1.1
Host: getvivix.com
Authorization: Bearer vvx_live_…HTTP/1.1 200 OK
{
"tier": "pro",
"credits_balance": 12847,
"rate_limit": { "per_minute": 240, "max_concurrent": 5 },
"request_id": "req_4f2a9c81b3d0",
"models": [
{
"slug": "grok-imagine-image-quality",
"name": "Grok Imagine Image Quality",
"category": "image",
"kind": "image",
"creator": "xai",
"description": "xAI's quality-focused image generation and editing — sharper realism, better text rendering, tighter prompt following",
"modes": ["text-to-image", "image-to-image", "image-editing"],
"params": {
"prompt": { "type": "string", "required": true },
"aspect_ratio": { "type": "enum", "required": false, "values": ["1:1", "1:1 · 2K", "16:9", "16:9 · 2K"] },
"size": {
"type": "enum",
"required": false,
"presets_only": true,
"values": ["1024x1024", "2048x2048", "1408x768", "2752x1504"],
"options": [
{ "size": "1024x1024", "tag": "1:1", "label": "1024 × 1024" },
{ "size": "2048x2048", "tag": "1:1 · 2K", "label": "2048 × 2048" }
]
},
"resolution": { "type": "enum", "required": false, "values": ["1k", "2k"] },
"reference_images": { "type": "string[]", "required": false, "min": 0, "max": 3 },
"number_results": { "type": "number", "required": false, "max": 4, "default": 1 },
"seed": { "type": "number", "required": false }
},
"prompt_max_chars": 2000,
"credits_band": { "min": 150, "max": 210, "flat": false },
"enhance_supported": false,
"example_request": {
"model": "grok-imagine-image-quality",
"prompt": "A cinematic mountain landscape at golden hour"
}
},
{
"slug": "wan2-7",
"name": "Wan2.7",
"category": "video",
"kind": "video",
"creator": "alibaba",
"description": "The first Wan with reference-to-video and video-to-video editing — four modes, native audio, multi-shot scenes",
"modes": ["text-to-video", "image-to-video", "video-to-video"],
"params": {
"prompt": { "type": "string", "required": true },
"aspect_ratio": { "type": "enum", "required": false, "values": ["16:9", "9:16", "1:1", "4:3", "3:4"] },
"resolution": { "type": "enum", "required": false, "values": ["720p", "1080p"], "default": "1080p" },
"duration": { "type": "number", "required": false, "min": 2, "max": 15, "default": 5 },
"audio": { "type": "boolean", "required": false, "default": true },
"reference_images": { "type": "string[]", "required": false, "min": 0, "max": 2 },
"seed": { "type": "number", "required": false }
},
"prompt_max_chars": 2000,
"credits_band": { "min": 600, "max": 900, "flat": false },
"video_matrix": {
"dimensions": {
"720p": { "16:9": "1280x720", "9:16": "720x1280", "1:1": "960x960", "4:3": "1088x832", "3:4": "832x1088" },
"1080p": { "16:9": "1920x1080", "9:16": "1080x1920", "1:1": "1440x1440", "4:3": "1632x1248", "3:4": "1248x1632" }
}
},
"enhance_supported": false,
"example_request": {
"model": "wan2-7",
"prompt": "A cinematic mountain landscape at golden hour",
"aspect_ratio": "16:9",
"duration": 5,
"resolution": "1080p"
}
}
]
}Two things trimmed above for length, not accuracy: Grok Imagine Image Quality's aspect_ratio.values and size.values / size.options each list all 26 exact pixel pairs it accepts — 13 aspect ratios × two resolution tiers apiece (four and two shown, respectively) — presets_only: true means anything off that list is rejected outright, not rounded to the nearest match.
category and kindaren't the same thing. category groups a model the way our own Studio tabs do — a background-remover is "utility" there even though it's still image-in/image-out. kind is the plain media type (image / video / audio / text) — use it when you need to route a model to an image vs. video pipeline in your own app.
A few fields only appear when they apply: prompt_max_chars (models that take a prompt), credits_by_quality / credits_by_references (a model with a quality tier or a reference-image range prices each end of it), credits_from (a live per-your-account price for the default request, from the same engine that charges the generation — best-effort, omitted on a pricing hiccup rather than guessed), and video_matrix (exact width×height per resolution × aspect ratio, on video models with an audited table — shown above for Wan2.7).
params has a fixed set of possible keys — prompt, aspect_ratio, size, quality, resolution, duration, audio, reference_images, number_results, seed— and only the ones a given model actually accepts are present. Each key's own type tells you the input kind: string, enum (read values for the dropdown, default when given), number (respect min/max, or an explicit values list on some models' duration), boolean, or string[] on reference_images (respect max).
interface SizeEntry { size: string; tag?: string; label?: string }
interface ParamsSchema {
prompt?: { type: 'string'; required: boolean }
aspect_ratio?: { type: 'enum'; required: boolean; values: string[] }
size?: {
type: 'enum'; required: boolean; values: string[]; presets_only: boolean
options?: SizeEntry[]
values_by_quality?: Record<string, string[]> // e.g. GPT Image 2's "low" tier
}
quality?: { type: 'enum'; required: boolean; values: string[]; default: string }
resolution?: { type: 'enum'; required: boolean; values: string[]; default?: string }
duration?: { type: 'enum' | 'number'; required: boolean; values?: number[]; min?: number; max?: number; default?: number }
audio?: { type: 'boolean'; required: boolean; default?: boolean }
reference_images?: { type: 'string[]'; required: boolean; min: number; max: number }
number_results?: { type: 'number'; required: boolean; max: number; default: number }
seed?: { type: 'number'; required: boolean }
}
interface Model {
slug: string
name: string
category: 'image' | 'video' | 'audio' | 'text' | 'utility' | 'threed'
kind: 'image' | 'video' | 'audio' | 'text'
creator: string
description: string
modes: string[]
params: ParamsSchema
prompt_max_chars?: number
credits_band: { min: number; max: number; flat: boolean }
credits_from?: number
credits_by_quality?: Record<string, number>
credits_by_references?: Record<string, number>
video_matrix?: { dimensions: Record<string, Record<string, string>> }
enhance_supported: boolean
example_request: Record<string, unknown>
}
const res = await fetch('https://getvivix.com/api/v1/models', {
headers: { Authorization: `Bearer ${process.env.VIVIX_KEY}` },
})
const { models, request_id } = await res.json() as { models: Model[]; request_id: string }Common errors — see the full error reference:
401 AUTH_MISSING — no Authorization header sent401 KEY_INVALID — header present but the key doesn't match a live one401 KEY_REVOKED — the key existed but was revoked403 TIER_LOCKED — Pro, Pro Plus, or Ultimate only (Free/Standard get 403 here)