# CyHUB API > Generate images, video and audio over an HTTP API with the same models and prices as the Cyber AI bots. One key for every model, paid from the account balance. API base URL: https://api.cyhub.ai/v1. Every request carries the header `Authorization: Bearer `. Create a key in the dashboard (https://cyhub.ai/cabinet/keys) after verifying your email. Workflow: choose a model (GET /v1/models), read the fields of its settings (GET /v1/models/{model_key}), optionally check the price (POST /v1/price), submit a task (POST /v1/tasks), poll it (GET /v1/tasks/{id}) until the status is succeeded and download the result files. An error comes as `{"error": {"code", "message"}}`: branch on code and show message to a person. Language of texts: ?lang=ru or ?lang=en, or the Accept-Language header; Russian without either. Every documentation page has a Markdown version: add .md to its address, for example https://api.cyhub.ai/docs/tasks.md?lang=en. This file in Russian: https://api.cyhub.ai/llms.txt?lang=ru --- # Start > Your first request to the CyHUB API. ## Where to start One key opens every CyHUB model available through the API. Choose a model, submit a task and collect the result: the same models and prices as in the bots. 1. [Create a key](https://cyhub.ai/cabinet/keys): In the dashboard, after verifying your email. 2. [Choose a model](https://api.cyhub.ai/models): Parameters and examples on the model page. 3. [Submit a task](https://api.cyhub.ai/docs/generations.md?lang=en): The model and its settings in POST /v1/tasks. 4. [Collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): Task status and files, kept for 7 days. ## First request Replace YOUR_API_KEY with your key. The request checks the key and shows the balance; it does not start a generation. ```bash curl "https://api.cyhub.ai/v1/me" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(f"{API}/me", headers=HEADERS, timeout=30) response.raise_for_status() me = response.json() for wallet in me["wallets"]: print(wallet["currency"], wallet["available_minor"]) ``` The response lists wallets: available_minor is what new tasks can spend, in kopecks for RUB. ## Next steps The general sections cover the connection, submitting tasks, tasks and results, files and errors. Each model has its own page with parameters, file rules and a request example. The formal description (OpenAPI) and a request console: /v1/docs. For AI agents: the documentation index is at /llms.txt, and every page has a Markdown version, just add .md to its address. GET /v1/models/schemas returns the schemas of all models in one request. [Set up the connection](https://api.cyhub.ai/docs/connection.md?lang=en) --- # Connection > API key, base URL and balance. ## API key Create a key in the dashboard under API keys after verifying your email. The secret is shown once: keep it on your server, never in a browser or public code. [Open API keys](https://cyhub.ai/cabinet/keys) Lost or possibly leaked key: revoke it in the dashboard and create a new one. A revoked key stops working immediately. ## Base URL and headers ``` https://api.cyhub.ai/v1 ``` Every request carries the Authorization header. Request bodies are UTF-8 JSON with Content-Type: application/json. ```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Language of texts in responses (error messages, model descriptions): the Accept-Language header with ru or en, or ?lang=en in the URL. Russian without either. ## Balance ```bash curl "https://api.cyhub.ai/v1/me" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(f"{API}/me", headers=HEADERS, timeout=30) response.raise_for_status() me = response.json() for wallet in me["wallets"]: print(wallet["currency"], wallet["available_minor"]) ``` The response has id (account number), platform, key (which key made the request) and wallets. A wallet has balance_minor (everything on the balance), reserved_minor (held by tasks in progress) and available_minor (what new tasks can spend). Amounts are in minor units: 15000 means ₽150. The balance is shared with Telegram and MAX when the accounts are linked. Top-ups are in RUB for now, on the Balance page of the dashboard. [Top up the balance](https://cyhub.ai/balance) --- # Create a generation > Model and settings in one request, price and safe retries. ## Model list GET /v1/models returns the same models, and GET /v1/models/{model_key} gives the JSON Schema of settings and documentation in the language of the request. All models with their schemas in one request: GET /v1/models/schemas. ```bash curl "https://api.cyhub.ai/v1/models" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(f"{API}/models", headers=HEADERS, timeout=30) response.raise_for_status() for model in response.json()["models"]: print(model["model_key"], model["title"], model["available"]) ``` [All models and their APIs](https://api.cyhub.ai/models) ## Submit a task A task is created with one request: the model key and its settings. The model page lists the fields. The Idempotency-Key header is optional, but it makes retries safe (see below). ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-1042" \ --data '{ "model": "veo", "settings": { "prompt": "A fishing boat emerges from the fog at dawn, seagulls calling", "mode": "text_to_video", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p" } }' ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "veo", "settings": { "prompt": "A fishing boat emerges from the fog at dawn, seagulls calling", "mode": "text_to_video", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p" } } headers = {**HEADERS, "Idempotency-Key": "order-1042"} response = requests.post(f"{API}/tasks", json=body, headers=headers, timeout=60) response.raise_for_status() task = response.json() print(task["id"], task["status"], task["amount_minor"]) ``` The response is 201 with the task: id, status (queued at first), amount_minor and currency (the price). The price is calculated on acceptance and reserved on the balance, charged after a successful generation; on failure or cancellation the reservation is released. With insufficient funds the response is 402 insufficient_funds: no task is created and no money is touched. An unknown field in settings is 422 unknown_setting, an unsuitable value is 422 invalid_settings. [Check the status and get the result](https://api.cyhub.ai/docs/tasks.md?lang=en) ## Check the price first Send the same model and settings to POST /v1/price: no task is created and no money is touched. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "veo", "settings": { "prompt": "A fishing boat emerges from the fog at dawn, seagulls calling", "mode": "text_to_video", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p" } }' ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "veo", "settings": { "prompt": "A fishing boat emerges from the fog at dawn, seagulls calling", "mode": "text_to_video", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p" } } headers = HEADERS response = requests.post(f"{API}/price", json=body, headers=headers, timeout=60) response.raise_for_status() price = response.json() print(price["amount_minor"], price["currency"], price["available_minor"]) ``` The response has credits (internal model units), amount_minor and currency (the price in money), regular_minor and discount (the price without a discount and the discount, see below) and available_minor (what is available). The price is a reference: a new task is priced again on acceptance. ## Discounts When the account has a discount, amount_minor in POST /v1/price and in a task already includes it: this is what gets reserved and charged. Next to it are regular_minor (the price without a discount) and the discount percent: discount.percent in the price, discount_percent in a task. Without a discount regular_minor equals amount_minor and the percent is 0. GET /v1/discounts returns the discount level of the account, its spending and the prices of models on every level. While the account has no discounts, the response is {"active": false}. ```bash curl "https://api.cyhub.ai/v1/discounts" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(f"{API}/discounts", headers=HEADERS, timeout=30) response.raise_for_status() view = response.json() if view["active"]: print(view["tier_no"], view["turnover_minor"], view["remaining_minor"]) ``` ## Retrying requests Idempotency-Key is a label of one generation that your program makes up: a UUID or your own number such as order-1042. Pass it as a header or as the idempotency_key field in the body. ```http Idempotency-Key: order-1042 ``` The response was lost (connection drop, timeout): repeat the same request with the same label. The existing task comes back, without a second generation or a second reservation. The next generation needs a new label, even with the same settings. The same label with different settings is 409 idempotency_conflict. Retries with the same label may even run at the same time: the first one creates the task, the others wait for it and get the same task. If the first has not finished within 40 seconds, the response is 409 request_in_progress: retry a little later. --- # MCP plugin > CyHUB generations in Claude and ChatGPT: address and setup. ## Plugin address The CyberAI MCP plugin starts generations right from a chat with Claude or ChatGPT and spends the same balance as the website and the bots. Connect it with this address: ``` https://mcp.cyhub.ai/mcp ``` The plugin needs no API key. While connecting, our website opens: sign in to your account, check what the plugin asks for and press Allow. The plugin never gets your account password. The plugin shows finished images, video and audio right in the chat, in its own window with a player and a Download button. Claude Code and Codex have no such window: there the result comes as links. ## Claude - Open the Connectors section in Claude and add a custom connector (Add custom connector). - Name it CyberAI and paste the plugin address from the section above. - Press Connect, sign in to your account on our website and press Allow. - So that Claude does not ask for confirmation before every run, open the CyberAI connector in Connectors, press Custom in Tool permissions and choose Always allow. Spending is still capped by the limits in your account. - Turn on the CyberAI connector in a chat and ask, for example, for a picture. The connector works in Claude on the web, in the app and on the phone. ## ChatGPT CyberAI is in the ChatGPT plugin catalog. [Open CyberAI in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ab7a35807d48191970dd1bdb063b785) - Open the plugin page with the link above and connect it. - Sign in to your account on our website and press Allow. - Pick the CyberAI plugin in the chat: otherwise ChatGPT does not use it. All models are available in ChatGPT except the 18+ mode of Grok Video. If the plugin is not in the catalog of your country, connect it by address in developer mode: - In the ChatGPT settings open Plugins and turn on Developer mode. - Create an app: open Settings > Plugins > Browse catalog > Add > Create MCP app. Enter the name CyberAI, paste the plugin address from the section above, tick "I understand and want to continue" and press Create. - Sign in to your account on our website, press Allow, then pick CyberAI in the chat. ## Desktop tools Claude Code and Codex add the plugin with a command. Sign-in is the same: through our website and the Allow button. In Claude Code, run /mcp after the command and pick CyberAI. ``` claude mcp add --transport http cyberai https://mcp.cyhub.ai/mcp ``` ``` codex mcp add cyberai --url https://mcp.cyhub.ai/mcp ``` ## Access and spending - Without the Allow paid generations box the plugin only looks up models, the balance and generation history. - With the box ticked it starts paid generations from the account balance within the limits: per generation and per day. - Limits, paid generations and disconnecting the plugin are in the dashboard, on the MCP plugin tab. A disconnected plugin loses access at once. [Open MCP plugins in the dashboard](https://cyhub.ai/cabinet/connections) --- # Tasks and results > Statuses, results and task history. ## Check the status ```bash curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(f"{API}/tasks/TASK_ID", headers=HEADERS, timeout=30) response.raise_for_status() task = response.json() print(task["status"], task.get("stage")) ``` Replace TASK_ID with the id of the accepted task. While it is in progress, ask for the status every few seconds. The stage field says what the model is doing right now. | Status | Meaning | |---|---| | `queued` | The task is accepted and waiting in the queue. | | `running` | Generation is running. | | `succeeded` | The result is ready, the money is charged. | | `failed` | Generation failed, the reservation is released. The reason is in error. | | `cancelled` | The task was cancelled, the reservation is released. | ## Get the result A succeeded task has result: caption (a description of the result), texts (for example lyrics) and artifacts, files with index, kind (image, video, audio, document), filename, size and download_path. A failed task has the reason in error, in the language of the account. The reservation is already released; running again is a new task. A Seedance draft (a task with draft: true) has a draft field: whether it can be rebuilt in high quality (upscale_status), until when (upscale_until) and a ready request for that (upscale_request). A draft can be rebuilt once, with the upscale_draft mode of the same model. Other tasks have draft set to null. [Download result files](https://api.cyhub.ai/docs/files.md?lang=en#download) [Rebuilding a Seedance draft](https://api.cyhub.ai/models/seedance-2-5/api.md#upscale_draft) ## History ```bash curl "https://api.cyhub.ai/v1/tasks?limit=30" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(f"{API}/tasks?limit=30", headers=HEADERS, timeout=30) response.raise_for_status() page = response.json() for task in page["tasks"]: print(task["id"], task["model_key"], task["status"]) print("next:", page["next_cursor"]) ``` Filters: status and model (the model key); limit from 1 to 100. Next page: pass next_cursor from the response as before. --- # Files > References by URL, uploading your own files and downloading results. ## Files by URL URL list fields (for example image_urls) take direct https links to files: the server downloads them itself. A link must return the file without signing in, not a preview page. The model page says which fields exist, how many files and which formats. ```json { "prompt": "Make the background blue", "image_urls": [ "https://example.com/reference.jpg" ] } ``` ## Upload your own file Without a public link, upload the file to POST /v1/files (multipart/form-data, field file) and pass url from the response in the settings field. ```bash curl -X POST "https://api.cyhub.ai/v1/files" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@reference.jpg" ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} with open("reference.jpg", "rb") as handle: response = requests.post(f"{API}/files", files={"file": handle}, headers=HEADERS, timeout=120) response.raise_for_status() uploaded = response.json() print(uploaded["url"], uploaded["expires_at"]) ``` The response has id, kind (image, audio, video), size, url and expires_at. An uploaded file is kept for 7 days; submit the task right after uploading. | Kind | Formats | Size up to | |---|---|---| | Image | jpg, jpeg, png, webp | 30 MB | | Audio | mp3, wav, ogg, m4a, flac, aac | 20 MB | | Video | mp4, mov, webm | 200 MB | These are the upload ceilings. A model may have stricter limits; they are on its page and checked when the task is submitted. ## Download the result Result files are downloaded by download_path from the task with the same key. Replace 0 with the index of the file you need. ```bash curl "https://api.cyhub.ai/v1/tasks/TASK_ID/artifacts/0" \ -H "Authorization: Bearer YOUR_API_KEY" \ -o result.png ``` ```python import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(f"{API}/tasks/TASK_ID/artifacts/0", headers=HEADERS, timeout=300) response.raise_for_status() with open("result.png", "wb") as handle: handle.write(response.content) ``` > Results are kept for 7 days after the task finishes. Then files_expired becomes true and download_path null, while the task history stays. Keep the files on your side. --- # Errors and limits > What to do when a request fails. ## Error format Every error response has the same shape: code for the program, message for a person in the language of the request (Accept-Language or ?lang). ```json { "error": { "code": "insufficient_funds", "message": "Не хватает средств: нужно ещё 2500 в минорных единицах. Пополните баланс в кабинете." } } ``` ## Response codes | HTTP | Code | What to do | |---|---|---| | `401` | invalid_api_key | Check the key. Replace a revoked or missing key with a new one from the dashboard. | | `402` | insufficient_funds | Top up the balance; no task was created. | | `403` | model_not_allowed_for_key | The key may not use this model: the models of a key are changed in the dashboard, section API keys. | | `403` | key_daily_limit_exceeded | The daily spending limit of the key is reached; no task was created. The day follows Moscow time; the limit is changed in the dashboard. | | `404` | model_not_found, task_not_found | Check the model key (GET /v1/models) or the task id. | | `404` | artifact_expired | The result files are no longer stored. | | `404` | not_found | No such address. The response carries docs, openapi and llms fields with links to the API description. | | `405` | method_not_allowed | The address does not accept this request method: the allowed ones are in the Allow header, links to the API description are in the response. | | `409` | idempotency_conflict | A task with different settings already exists under this label; use a new label. | | `409` | request_in_progress | The task under this label is still being created: repeat the same request in a few seconds. | | `413` | request_too_large, file_too_large | Reduce the request body or the file. | | `422` | invalid_settings, unknown_setting | Check settings against the model page: details are in message. | | `422` | invalid_request, file_type, file_empty | Check the request shape, the file format and contents. | | `429` | rate_limited, too_many_active | Wait: the request limit or the concurrent task limit of the model was exceeded. | | `503` | model_unavailable, sg_unavailable | The model is under maintenance or the generation server is unavailable; retry later. | | `500` | internal_error | An error on our side; retry later and contact support if it persists. | ## Limits - 120 requests per minute per account; the keys of one account share the limit. - 30 requests with an invalid key per minute from one address. - JSON bodies up to 64 KB for tasks and price, up to 16 KB elsewhere. - Concurrent tasks of one model are limited the same way as in the bot: 429 too_many_active above the limit. - Up to 10 active keys per account. - A key can be limited to some models and to a daily spending limit (by default every model and no limit). The key sees its rights in GET /v1/me, and GET /v1/models with such a key lists only its models. A model may be temporarily disabled: available in GET /v1/models shows it in advance, and task submission answers 503 model_unavailable. --- # Seedance 2.5 API > Seedance 2.5 video by ByteDance with sound: from a description, from the first and last frames or from references, up to 30 seconds. References can be photos, videos and audio, quality up to 1080p. Your own video can be edited with a description or extended forward or backward. Two channels: the usual one and a usually cheaper one. On Channel 2 you can make a 480p draft first and rebuild the one you like once in 1080p. Developer: ByteDance Model key in the API: `seedance` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_5", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_5", "quality": "720p", "duration": 8, "aspect_ratio": "16:9", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_5", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_5", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A video from text alone, no files are sent. Value of the mode field: `text_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_5` (2.5) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `aspect_ratio` (Optional) Aspect ratio. adaptive is available only in version 2.5: the model picks the shape itself from the description. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `adaptive` (Chosen by the model) - Default: `"16:9"` #### `web_search` (Optional) Online search: the model pulls up-to-date information from the internet. Channel 1 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A video from a description ```json { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_5", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } } ``` A 480p draft to check the scene ```json { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Бармен подбрасывает шейкер, ловит его за спиной и подмигивает в камеру", "model": "seedance_2_5", "channel": "channel_2", "draft": true, "duration": 5, "aspect_ratio": "16:9" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The first frame, or the first and the last one: the model animates them by the description. Value of the mode field: `image_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_5` (2.5) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `image_urls` (Required) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 #### `aspect_ratio` (Optional) Aspect ratio; it only works in the 2.0 family on Channel 1. In version 2.5, and in every version on Channel 2, the first frame sets the video size and the chosen value is ignored: version 2.5 has a single choice here, adaptive. - Type: String - Allowed values: `adaptive` (As in the first frame) - Default: `"16:9"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - On Channel 2 the frame sets the video size in every version. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 2 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "seedance", "settings": { "mode": "image_to_video", "prompt": "Девушка поворачивается к камере и улыбается, волосы развеваются на ветру", "image_urls": [ "https://example.com/first-frame.jpg" ], "duration": 5 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Characters, style, motion and sound from your photos, videos and audio in a new clip. At least one photo or video is needed. Value of the mode field: `multimodal` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_5` (2.5) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `aspect_ratio` (Optional) Aspect ratio. adaptive is available only in version 2.5: the model picks the shape itself from the description and the references. On Channel 2 with reference videos this happens in every version, and the chosen value is ignored. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `adaptive` (Chosen by the model) - Default: `"16:9"` #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `video_urls` (Optional) Video reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Each video goes to the model whole, and its seconds are added to the price. - Type: List (String, uri) - Maximum items: 10 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Videos are URLs of MP4, MOV files: in version 2.5 up to 200 MB each and no longer than 30 seconds together, in the 2.0 family up to 50 MB and no longer than 15 seconds together. Each one at least 2 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - Files go to the model as they are and whole. The seconds of all reference videos are added to the video length in the price, a part of a second of each video counts as a whole one. On Channel 2 the price with a video is not below a floor that grows with the length of the clip. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - The description can refer to the files in the order of the URLs of each kind: @image1, @video1, @audio1 and so on. - On Channel 2 with reference videos the model picks the shape itself in every version. - To change or extend the video itself, use the video_edit and video_extend modes. Here a video is only a reference, but in version 2.5 on Channel 1 the model may take a description of an edit for an edit and refuse: then choose video_edit. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `video_urls` | Video | mp4, mov | 10 | 200 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A character and a camera move ```json { "model": "seedance", "settings": { "mode": "multimodal", "prompt": "Девушка с @image1 идёт по ночному городу под дождём, камера движется как в @video1", "image_urls": [ "https://example.com/girl.png" ], "video_urls": [ "https://example.com/camera-move.mp4" ], "duration": 8 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video edit > The model changes your video by the description: replace an object or a character, the background, the style. The rest stays as it was, with the length and shape of the video. Value of the mode field: `video_edit` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to change in the video: 3 to 20,000 characters, several languages are supported. The rest of the video stays as it was. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_5` (2.5) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `duration` (Optional) Does not apply: the clip comes out as long as your video. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Video editing and extension have no draft: leave it false. - Type: Boolean - Default: `false` #### `video_urls` (Required) The URL of the video to change. 4 to 30 seconds in version 2.5, up to 15 in the 2.0 family. It is @video1 in the description. - Type: List (String, uri) - Maximum items: 1 #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of a file (MP4, MOV): in version 2.5 up to 200 MB and no longer than 30 seconds, in the 2.0 family up to 50 MB and no longer than 15 seconds. At least 4 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - The video goes to the model as is and whole: to use another piece, trim the file beforehand. The price follows the length of the video: the new clip has as many seconds, and the input video adds as many again, a part of a second counts as a whole one. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - In the description your video is @video1, and photos and audio go in the order of their URLs: @image1, @audio1 and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4, mov | 1 | 200 MB | | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Replace an object in a video ```json { "model": "seedance", "settings": { "mode": "video_edit", "prompt": "Замени красный кораблик в @video1 на жёлтую резиновую уточку", "video_urls": [ "https://example.com/boat.mp4" ] } } ``` Another person from a photo ```json { "model": "seedance", "settings": { "mode": "video_edit", "prompt": "Замени девушку в @video1 на женщину с @image1, движения и фон те же", "video_urls": [ "https://example.com/dance.mp4" ], "image_urls": [ "https://example.com/woman.jpg" ], "quality": "1080p" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - A clip of the same length and shape as your video. In version 2.5 the length matches the video exactly, in the 2.0 family it is rounded up to a whole second. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video extension > The model continues your video with a new part of the chosen length, after the video or before it. Two clips come back: the new part and the same part joined with your video. Value of the mode field: `video_extend` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the new part: 3 to 20,000 characters, several languages are supported. Also write that the video should be extended, and in which direction. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_5` (2.5) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `duration` (Optional) Length of the new part in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second, and the seconds of your video are added to it. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Video editing and extension have no draft: leave it false. - Type: Boolean - Default: `false` #### `video_urls` (Required) The URL of the video to extend. 2 to 30 seconds in version 2.5, up to 15 in the 2.0 family. It is @video1 in the description. - Type: List (String, uri) - Maximum items: 1 #### `extend_direction` (Optional) Which side of your video to join the new part to: forward after the video, backward before it. The model takes the direction from the description, so state it there too. - Type: String - Allowed values: `forward` (After the video), `backward` (Before the video) - Default: `"forward"` #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of a file (MP4, MOV): in version 2.5 up to 200 MB and no longer than 30 seconds, in the 2.0 family up to 50 MB and no longer than 15 seconds. At least 2 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - The model takes the direction from the description: write that the video should be extended and what happens next, or for an extension backward write "extend backward" and what happened before the start. extend_direction only sets which side of your video we join the new part to. - On Channel 1 only version 2.5 can extend a video: for the 2.0 family choose Channel 2. - The video goes to the model as is and whole: to use another piece, trim the file beforehand. The seconds of your video are added to the length of the new part in the price, a part of a second counts as a whole one. On Channel 2 the price is not below a floor that grows with the length of the part. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - In the description your video is @video1, and photos and audio go in the order of their URLs: @image1, @audio1 and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4, mov | 1 | 200 MB | | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. What happened next ```json { "model": "seedance", "settings": { "mode": "video_extend", "prompt": "Продли @video1: кораблик проплывает под мостиком и скрывается за поворотом", "video_urls": [ "https://example.com/boat.mp4" ], "duration": 5, "channel": "channel_2" } } ``` What happened before ```json { "model": "seedance", "settings": { "mode": "video_extend", "prompt": "Продли @video1 назад: рука опускает бумажный кораблик на воду", "video_urls": [ "https://example.com/boat.mp4" ], "duration": 4, "extend_direction": "backward" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - The new part comes first, then the same part joined with your video on the extend_direction side. The joined clip has the frame size of the new part, the sound of your video is kept. - If joining fails, only the new part comes, with an explanation in texts. The price is the same: the part is ready. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | The new part. | | `video` | mp4 | 0 or 1 | Your video and the new part as one clip. Absent if joining fails. | `result.texts`: An explanation if joining fails. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Draft rebuild > Rebuild a finished draft in 1080p: the same clip with the same scene, motion and sound. Once per draft and only within 7 days after it was made. Value of the mode field: `upscale_draft` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `draft_task_id` (Required) id of the draft task from /v1/tasks: a succeeded Seedance 2.5 task on Channel 2 with draft: true from your account. - Type: String - Minimum characters: 1 - Maximum characters: 36 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - A rebuild has no other settings: the model takes the description, files, length, aspect ratio and sound from the draft. - A rebuild is always 1080p. It costs as much as a regular 1080p clip with the settings of the draft; get the price in advance from /v1/price with the same settings. - A draft can be rebuilt once and only within 7 days after it was made. The exact deadline and whether it can be rebuilt now are in the draft field of the draft task. - A draft that is not ready yet, failed, has already been rebuilt or is being rebuilt, belongs to another account or has expired gets a refusal with an error code, and no money is reserved. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Rebuild a draft in 1080p ```json { "model": "seedance", "settings": { "mode": "upscale_draft", "draft_task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - A 1080p video. A failed rebuild is not charged. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Seedance 2.5: features and prices](https://api.cyhub.ai/models/seedance-2-5) - Other versions: [Seedance 2.0 API](https://api.cyhub.ai/en/models/seedance-2/api.md), [Seedance 2.0 Fast API](https://api.cyhub.ai/en/models/seedance-2-fast/api.md), [Seedance 2.0 Mini API](https://api.cyhub.ai/en/models/seedance-2-mini/api.md) - Similar models: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Seedance 2.0 API > Seedance 2.0 video by ByteDance with sound: from a description, from the first and last frames or from references, up to 15 seconds. References can be photos, videos and audio. Your own video can be edited with a description, and on Channel 2 also extended forward or backward. The only Seedance version with 4K. Two channels: the usual one and a usually cheaper one. Developer: ByteDance Model key in the API: `seedance` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2", "quality": "720p", "duration": 8, "aspect_ratio": "16:9", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A video from text alone, no files are sent. Value of the mode field: `text_to_video` This page is about Seedance 2.0: send model = seedance_2. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2` (Pro 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p`, `4k` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `aspect_ratio` (Optional) Aspect ratio. adaptive is available only in version 2.5: the model picks the shape itself from the description. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` #### `web_search` (Optional) Online search: the model pulls up-to-date information from the internet. Channel 1 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A video from a description ```json { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The first frame, or the first and the last one: the model animates them by the description. Value of the mode field: `image_to_video` This page is about Seedance 2.0: send model = seedance_2. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2` (Pro 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p`, `4k` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `image_urls` (Required) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 #### `aspect_ratio` (Optional) Aspect ratio; it only works in the 2.0 family on Channel 1. In version 2.5, and in every version on Channel 2, the first frame sets the video size and the chosen value is ignored: version 2.5 has a single choice here, adaptive. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - On Channel 2 the frame sets the video size in every version. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 2 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. From the first frame to the last ```json { "model": "seedance", "settings": { "mode": "image_to_video", "prompt": "Бутон медленно раскрывается в цветок, мягкий утренний свет", "model": "seedance_2", "quality": "1080p", "aspect_ratio": "9:16", "image_urls": [ "https://example.com/bud.jpg", "https://example.com/flower.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Characters, style, motion and sound from your photos, videos and audio in a new clip. At least one photo or video is needed. Value of the mode field: `multimodal` This page is about Seedance 2.0: send model = seedance_2. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2` (Pro 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p`, `4k` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `aspect_ratio` (Optional) Aspect ratio. adaptive is available only in version 2.5: the model picks the shape itself from the description and the references. On Channel 2 with reference videos this happens in every version, and the chosen value is ignored. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `video_urls` (Optional) Video reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Each video goes to the model whole, and its seconds are added to the price. - Type: List (String, uri) - Maximum items: 10 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Videos are URLs of MP4, MOV files: in version 2.5 up to 200 MB each and no longer than 30 seconds together, in the 2.0 family up to 50 MB and no longer than 15 seconds together. Each one at least 2 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - Files go to the model as they are and whole. The seconds of all reference videos are added to the video length in the price, a part of a second of each video counts as a whole one. On Channel 2 the price with a video is not below a floor that grows with the length of the clip. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - The description can refer to the files in the order of the URLs of each kind: @image1, @video1, @audio1 and so on. - On Channel 2 with reference videos the model picks the shape itself in every version. - To change or extend the video itself, use the video_edit and video_extend modes. Here a video is only a reference, but in version 2.5 on Channel 1 the model may take a description of an edit for an edit and refuse: then choose video_edit. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `video_urls` | Video | mp4, mov | 10 | 200 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A voice from audio ```json { "model": "seedance", "settings": { "mode": "multimodal", "prompt": "Мужчина с @image1 рассказывает историю у камина голосом с @audio1", "model": "seedance_2", "quality": "1080p", "image_urls": [ "https://example.com/man.jpg" ], "audio_urls": [ "https://example.com/voice.mp3" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video edit > The model changes your video by the description: replace an object or a character, the background, the style. The rest stays as it was, with the length and shape of the video. Value of the mode field: `video_edit` This page is about Seedance 2.0: send model = seedance_2. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to change in the video: 3 to 20,000 characters, several languages are supported. The rest of the video stays as it was. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2` (Pro 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p`, `4k` - Default: `"720p"` #### `duration` (Optional) Does not apply: the clip comes out as long as your video. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Video editing and extension have no draft: leave it false. - Type: Boolean - Default: `false` #### `video_urls` (Required) The URL of the video to change. 4 to 30 seconds in version 2.5, up to 15 in the 2.0 family. It is @video1 in the description. - Type: List (String, uri) - Maximum items: 1 #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of a file (MP4, MOV): in version 2.5 up to 200 MB and no longer than 30 seconds, in the 2.0 family up to 50 MB and no longer than 15 seconds. At least 4 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - The video goes to the model as is and whole: to use another piece, trim the file beforehand. The price follows the length of the video: the new clip has as many seconds, and the input video adds as many again, a part of a second counts as a whole one. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - In the description your video is @video1, and photos and audio go in the order of their URLs: @image1, @audio1 and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4, mov | 1 | 200 MB | | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Replace an object in a video ```json { "model": "seedance", "settings": { "mode": "video_edit", "prompt": "Замени красный кораблик в @video1 на жёлтую резиновую уточку", "video_urls": [ "https://example.com/boat.mp4" ], "model": "seedance_2" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - A clip of the same length and shape as your video. In version 2.5 the length matches the video exactly, in the 2.0 family it is rounded up to a whole second. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video extension > The model continues your video with a new part of the chosen length, after the video or before it. Two clips come back: the new part and the same part joined with your video. Value of the mode field: `video_extend` This page is about Seedance 2.0: send model = seedance_2. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the new part: 3 to 20,000 characters, several languages are supported. Also write that the video should be extended, and in which direction. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2` (Pro 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p`, `1080p`, `4k` - Default: `"720p"` #### `duration` (Optional) Length of the new part in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second, and the seconds of your video are added to it. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Video editing and extension have no draft: leave it false. - Type: Boolean - Default: `false` #### `video_urls` (Required) The URL of the video to extend. 2 to 30 seconds in version 2.5, up to 15 in the 2.0 family. It is @video1 in the description. - Type: List (String, uri) - Maximum items: 1 #### `extend_direction` (Optional) Which side of your video to join the new part to: forward after the video, backward before it. The model takes the direction from the description, so state it there too. - Type: String - Allowed values: `forward` (After the video), `backward` (Before the video) - Default: `"forward"` #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of a file (MP4, MOV): in version 2.5 up to 200 MB and no longer than 30 seconds, in the 2.0 family up to 50 MB and no longer than 15 seconds. At least 2 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - The model takes the direction from the description: write that the video should be extended and what happens next, or for an extension backward write "extend backward" and what happened before the start. extend_direction only sets which side of your video we join the new part to. - On Channel 1 only version 2.5 can extend a video: for the 2.0 family choose Channel 2. - The video goes to the model as is and whole: to use another piece, trim the file beforehand. The seconds of your video are added to the length of the new part in the price, a part of a second counts as a whole one. On Channel 2 the price is not below a floor that grows with the length of the part. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - In the description your video is @video1, and photos and audio go in the order of their URLs: @image1, @audio1 and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4, mov | 1 | 200 MB | | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. What happened next ```json { "model": "seedance", "settings": { "mode": "video_extend", "prompt": "Продли @video1: кораблик проплывает под мостиком и скрывается за поворотом", "video_urls": [ "https://example.com/boat.mp4" ], "duration": 5, "channel": "channel_2", "model": "seedance_2" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - The new part comes first, then the same part joined with your video on the extend_direction side. The joined clip has the frame size of the new part, the sound of your video is kept. - If joining fails, only the new part comes, with an explanation in texts. The price is the same: the part is ready. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | The new part. | | `video` | mp4 | 0 or 1 | Your video and the new part as one clip. Absent if joining fails. | `result.texts`: An explanation if joining fails. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Seedance 2.0: features and prices](https://api.cyhub.ai/models/seedance-2) - Other versions: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Seedance 2.0 Fast API](https://api.cyhub.ai/en/models/seedance-2-fast/api.md), [Seedance 2.0 Mini API](https://api.cyhub.ai/en/models/seedance-2-mini/api.md) - Similar models: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Seedance 2.0 Fast API > Seedance 2.0 Fast video by ByteDance with sound: from a description, from the first and last frames or from references, up to 15 seconds. A fast version, 480p or 720p. References can be photos, videos and audio. Your own video can be edited with a description, and on Channel 2 also extended forward or backward. Two channels: the usual one and a usually cheaper one. Developer: ByteDance Model key in the API: `seedance` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план", "model": "seedance_2_fast", "quality": "480p", "duration": 5, "aspect_ratio": "9:16", "channel": "channel_2" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план", "model": "seedance_2_fast", "quality": "480p", "duration": 5, "aspect_ratio": "9:16", "channel": "channel_2", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план", "model": "seedance_2_fast", "quality": "480p", "duration": 5, "aspect_ratio": "9:16", "channel": "channel_2" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план", "model": "seedance_2_fast", "quality": "480p", "duration": 5, "aspect_ratio": "9:16", "channel": "channel_2" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A video from text alone, no files are sent. Value of the mode field: `text_to_video` This page is about Seedance 2.0 Fast: send model = seedance_2_fast. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_fast` (Fast 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `aspect_ratio` (Optional) Aspect ratio. adaptive is available only in version 2.5: the model picks the shape itself from the description. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` #### `web_search` (Optional) Online search: the model pulls up-to-date information from the internet. Channel 1 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Cheaper, through Channel 2 ```json { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план", "model": "seedance_2_fast", "quality": "480p", "duration": 5, "aspect_ratio": "9:16", "channel": "channel_2" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The first frame, or the first and the last one: the model animates them by the description. Value of the mode field: `image_to_video` This page is about Seedance 2.0 Fast: send model = seedance_2_fast. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_fast` (Fast 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `image_urls` (Required) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 #### `aspect_ratio` (Optional) Aspect ratio; it only works in the 2.0 family on Channel 1. In version 2.5, and in every version on Channel 2, the first frame sets the video size and the chosen value is ignored: version 2.5 has a single choice here, adaptive. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - On Channel 2 the frame sets the video size in every version. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 2 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "seedance", "settings": { "mode": "image_to_video", "prompt": "Девушка поворачивается к камере и улыбается, волосы развеваются на ветру", "image_urls": [ "https://example.com/first-frame.jpg" ], "duration": 5, "model": "seedance_2_fast" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Characters, style, motion and sound from your photos, videos and audio in a new clip. At least one photo or video is needed. Value of the mode field: `multimodal` This page is about Seedance 2.0 Fast: send model = seedance_2_fast. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_fast` (Fast 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `aspect_ratio` (Optional) Aspect ratio. adaptive is available only in version 2.5: the model picks the shape itself from the description and the references. On Channel 2 with reference videos this happens in every version, and the chosen value is ignored. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `video_urls` (Optional) Video reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Each video goes to the model whole, and its seconds are added to the price. - Type: List (String, uri) - Maximum items: 10 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Videos are URLs of MP4, MOV files: in version 2.5 up to 200 MB each and no longer than 30 seconds together, in the 2.0 family up to 50 MB and no longer than 15 seconds together. Each one at least 2 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - Files go to the model as they are and whole. The seconds of all reference videos are added to the video length in the price, a part of a second of each video counts as a whole one. On Channel 2 the price with a video is not below a floor that grows with the length of the clip. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - The description can refer to the files in the order of the URLs of each kind: @image1, @video1, @audio1 and so on. - On Channel 2 with reference videos the model picks the shape itself in every version. - To change or extend the video itself, use the video_edit and video_extend modes. Here a video is only a reference, but in version 2.5 on Channel 1 the model may take a description of an edit for an edit and refuse: then choose video_edit. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `video_urls` | Video | mp4, mov | 10 | 200 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A character and a camera move ```json { "model": "seedance", "settings": { "mode": "multimodal", "prompt": "Девушка с @image1 идёт по ночному городу под дождём, камера движется как в @video1", "image_urls": [ "https://example.com/girl.png" ], "video_urls": [ "https://example.com/camera-move.mp4" ], "duration": 8, "model": "seedance_2_fast" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video edit > The model changes your video by the description: replace an object or a character, the background, the style. The rest stays as it was, with the length and shape of the video. Value of the mode field: `video_edit` This page is about Seedance 2.0 Fast: send model = seedance_2_fast. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to change in the video: 3 to 20,000 characters, several languages are supported. The rest of the video stays as it was. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_fast` (Fast 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Does not apply: the clip comes out as long as your video. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Video editing and extension have no draft: leave it false. - Type: Boolean - Default: `false` #### `video_urls` (Required) The URL of the video to change. 4 to 30 seconds in version 2.5, up to 15 in the 2.0 family. It is @video1 in the description. - Type: List (String, uri) - Maximum items: 1 #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of a file (MP4, MOV): in version 2.5 up to 200 MB and no longer than 30 seconds, in the 2.0 family up to 50 MB and no longer than 15 seconds. At least 4 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - The video goes to the model as is and whole: to use another piece, trim the file beforehand. The price follows the length of the video: the new clip has as many seconds, and the input video adds as many again, a part of a second counts as a whole one. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - In the description your video is @video1, and photos and audio go in the order of their URLs: @image1, @audio1 and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4, mov | 1 | 200 MB | | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Replace an object in a video ```json { "model": "seedance", "settings": { "mode": "video_edit", "prompt": "Замени красный кораблик в @video1 на жёлтую резиновую уточку", "video_urls": [ "https://example.com/boat.mp4" ], "model": "seedance_2_fast" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - A clip of the same length and shape as your video. In version 2.5 the length matches the video exactly, in the 2.0 family it is rounded up to a whole second. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video extension > The model continues your video with a new part of the chosen length, after the video or before it. Two clips come back: the new part and the same part joined with your video. Value of the mode field: `video_extend` This page is about Seedance 2.0 Fast: send model = seedance_2_fast. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the new part: 3 to 20,000 characters, several languages are supported. Also write that the video should be extended, and in which direction. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_fast` (Fast 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Length of the new part in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second, and the seconds of your video are added to it. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Video editing and extension have no draft: leave it false. - Type: Boolean - Default: `false` #### `video_urls` (Required) The URL of the video to extend. 2 to 30 seconds in version 2.5, up to 15 in the 2.0 family. It is @video1 in the description. - Type: List (String, uri) - Maximum items: 1 #### `extend_direction` (Optional) Which side of your video to join the new part to: forward after the video, backward before it. The model takes the direction from the description, so state it there too. - Type: String - Allowed values: `forward` (After the video), `backward` (Before the video) - Default: `"forward"` #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of a file (MP4, MOV): in version 2.5 up to 200 MB and no longer than 30 seconds, in the 2.0 family up to 50 MB and no longer than 15 seconds. At least 2 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - The model takes the direction from the description: write that the video should be extended and what happens next, or for an extension backward write "extend backward" and what happened before the start. extend_direction only sets which side of your video we join the new part to. - On Channel 1 only version 2.5 can extend a video: for the 2.0 family choose Channel 2. - The video goes to the model as is and whole: to use another piece, trim the file beforehand. The seconds of your video are added to the length of the new part in the price, a part of a second counts as a whole one. On Channel 2 the price is not below a floor that grows with the length of the part. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - In the description your video is @video1, and photos and audio go in the order of their URLs: @image1, @audio1 and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4, mov | 1 | 200 MB | | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. What happened next ```json { "model": "seedance", "settings": { "mode": "video_extend", "prompt": "Продли @video1: кораблик проплывает под мостиком и скрывается за поворотом", "video_urls": [ "https://example.com/boat.mp4" ], "duration": 5, "channel": "channel_2", "model": "seedance_2_fast" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - The new part comes first, then the same part joined with your video on the extend_direction side. The joined clip has the frame size of the new part, the sound of your video is kept. - If joining fails, only the new part comes, with an explanation in texts. The price is the same: the part is ready. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | The new part. | | `video` | mp4 | 0 or 1 | Your video and the new part as one clip. Absent if joining fails. | `result.texts`: An explanation if joining fails. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Seedance 2.0 Fast: features and prices](https://api.cyhub.ai/models/seedance-2-fast) - Other versions: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Seedance 2.0 API](https://api.cyhub.ai/en/models/seedance-2/api.md), [Seedance 2.0 Mini API](https://api.cyhub.ai/en/models/seedance-2-mini/api.md) - Similar models: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Seedance 2.0 Mini API > Seedance 2.0 Mini video by ByteDance with sound: from a description, from the first and last frames or from references, up to 15 seconds. The cheapest Seedance version, 480p or 720p. References can be photos, videos and audio. Your own video can be edited with a description, and on Channel 2 also extended forward or backward. Two channels: the usual one and a usually cheaper one. Developer: ByteDance Model key in the API: `seedance` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_mini", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_mini", "quality": "720p", "duration": 8, "aspect_ratio": "16:9", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_mini", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_mini", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A video from text alone, no files are sent. Value of the mode field: `text_to_video` This page is about Seedance 2.0 Mini: send model = seedance_2_mini. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_mini` (Mini 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `aspect_ratio` (Optional) Aspect ratio. adaptive is available only in version 2.5: the model picks the shape itself from the description. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` #### `web_search` (Optional) Online search: the model pulls up-to-date information from the internet. Channel 1 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A video from a description ```json { "model": "seedance", "settings": { "mode": "text_to_video", "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает", "model": "seedance_2_mini", "quality": "720p", "duration": 8, "aspect_ratio": "16:9" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The first frame, or the first and the last one: the model animates them by the description. Value of the mode field: `image_to_video` This page is about Seedance 2.0 Mini: send model = seedance_2_mini. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_mini` (Mini 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `image_urls` (Required) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 #### `aspect_ratio` (Optional) Aspect ratio; it only works in the 2.0 family on Channel 1. In version 2.5, and in every version on Channel 2, the first frame sets the video size and the chosen value is ignored: version 2.5 has a single choice here, adaptive. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - On Channel 2 the frame sets the video size in every version. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 2 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "seedance", "settings": { "mode": "image_to_video", "prompt": "Девушка поворачивается к камере и улыбается, волосы развеваются на ветру", "image_urls": [ "https://example.com/first-frame.jpg" ], "duration": 5, "model": "seedance_2_mini" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Characters, style, motion and sound from your photos, videos and audio in a new clip. At least one photo or video is needed. Value of the mode field: `multimodal` This page is about Seedance 2.0 Mini: send model = seedance_2_mini. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: 3 to 20,000 characters, several languages are supported. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_mini` (Mini 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Video length in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Draft: a low-cost 480p clip to check the scene, motion and sound before paying for high quality. It costs as much as a regular 480p clip, and quality does not apply to it. Only version 2.5 on Channel 2 has drafts: with another version or channel the task is not accepted. If you like the draft, it can be rebuilt once in 1080p with the upscale_draft mode within 7 days after it was made: the scene, motion and sound stay the same, and the rebuild costs as much as a regular 1080p clip. - Type: Boolean - Default: `false` #### `aspect_ratio` (Optional) Aspect ratio. adaptive is available only in version 2.5: the model picks the shape itself from the description and the references. On Channel 2 with reference videos this happens in every version, and the chosen value is ignored. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` - Default: `"16:9"` #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `video_urls` (Optional) Video reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Each video goes to the model whole, and its seconds are added to the price. - Type: List (String, uri) - Maximum items: 10 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Videos are URLs of MP4, MOV files: in version 2.5 up to 200 MB each and no longer than 30 seconds together, in the 2.0 family up to 50 MB and no longer than 15 seconds together. Each one at least 2 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - Files go to the model as they are and whole. The seconds of all reference videos are added to the video length in the price, a part of a second of each video counts as a whole one. On Channel 2 the price with a video is not below a floor that grows with the length of the clip. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - The description can refer to the files in the order of the URLs of each kind: @image1, @video1, @audio1 and so on. - On Channel 2 with reference videos the model picks the shape itself in every version. - To change or extend the video itself, use the video_edit and video_extend modes. Here a video is only a reference, but in version 2.5 on Channel 1 the model may take a description of an edit for an edit and refuse: then choose video_edit. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `video_urls` | Video | mp4, mov | 10 | 200 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A character and a camera move ```json { "model": "seedance", "settings": { "mode": "multimodal", "prompt": "Девушка с @image1 идёт по ночному городу под дождём, камера движется как в @video1", "image_urls": [ "https://example.com/girl.png" ], "video_urls": [ "https://example.com/camera-move.mp4" ], "duration": 8, "model": "seedance_2_mini" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - With draft: true you get a 480p draft. Such a task has a draft field: until when it can be rebuilt in 1080p, whether it can be rebuilt now and a ready request for the rebuild. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video edit > The model changes your video by the description: replace an object or a character, the background, the style. The rest stays as it was, with the length and shape of the video. Value of the mode field: `video_edit` This page is about Seedance 2.0 Mini: send model = seedance_2_mini. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to change in the video: 3 to 20,000 characters, several languages are supported. The rest of the video stays as it was. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_mini` (Mini 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Does not apply: the clip comes out as long as your video. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Video editing and extension have no draft: leave it false. - Type: Boolean - Default: `false` #### `video_urls` (Required) The URL of the video to change. 4 to 30 seconds in version 2.5, up to 15 in the 2.0 family. It is @video1 in the description. - Type: List (String, uri) - Maximum items: 1 #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of a file (MP4, MOV): in version 2.5 up to 200 MB and no longer than 30 seconds, in the 2.0 family up to 50 MB and no longer than 15 seconds. At least 4 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - The video goes to the model as is and whole: to use another piece, trim the file beforehand. The price follows the length of the video: the new clip has as many seconds, and the input video adds as many again, a part of a second counts as a whole one. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - In the description your video is @video1, and photos and audio go in the order of their URLs: @image1, @audio1 and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4, mov | 1 | 200 MB | | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Replace an object in a video ```json { "model": "seedance", "settings": { "mode": "video_edit", "prompt": "Замени красный кораблик в @video1 на жёлтую резиновую уточку", "video_urls": [ "https://example.com/boat.mp4" ], "model": "seedance_2_mini" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - A clip of the same length and shape as your video. In version 2.5 the length matches the video exactly, in the 2.0 family it is rounded up to a whole second. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video extension > The model continues your video with a new part of the chosen length, after the video or before it. Two clips come back: the new part and the same part joined with your video. Value of the mode field: `video_extend` This page is about Seedance 2.0 Mini: send model = seedance_2_mini. Without the model field the task runs on seedance_2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the new part: 3 to 20,000 characters, several languages are supported. Also write that the video should be extended, and in which direction. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `model` (Optional) Version. 2.5 is the newest and makes clips up to 30 seconds, Pro 2.0 is the only one with 4K, Fast 2.0 is fast, Mini 2.0 is the cheapest. - Type: String - Allowed values: `seedance_2_mini` (Mini 2.0) - Default: `"seedance_2_5"` #### `quality` (Optional) Video quality; the price depends on it. 1080p is available in 2.5 and Pro 2.0, 4K only in Pro 2.0. A draft is always 480p, this field does not apply to it. - Type: String - Allowed values: `480p`, `720p` - Default: `"720p"` #### `duration` (Optional) Length of the new part in seconds: 4 to 30 in version 2.5, up to 15 in the 2.0 family. The price is per second, and the seconds of your video are added to it. - Type: Integer - Minimum: 4 - Maximum: 30 - Default: `5` #### `generate_audio` (Optional) Generate sound together with the video. - Type: Boolean - Default: `true` #### `channel` (Optional) Which channel the generation goes through: the model is the same, the price and the checks differ. Channel 1 is the usual one and accepts photos of people. Channel 2 is usually cheaper, but it rejects photos of real people and prohibited subjects, and it has no online search. With a video as input Channel 2 has a price floor that grows with the length of the clip, so with a short video it can cost more. A refusal of a channel is not charged. - Type: String - Allowed values: `channel_1` (Channel 1), `channel_2` (Channel 2) - Default: `"channel_1"` #### `draft` (Optional) Video editing and extension have no draft: leave it false. - Type: Boolean - Default: `false` #### `video_urls` (Required) The URL of the video to extend. 2 to 30 seconds in version 2.5, up to 15 in the 2.0 family. It is @video1 in the description. - Type: List (String, uri) - Maximum items: 1 #### `extend_direction` (Optional) Which side of your video to join the new part to: forward after the video, backward before it. The model takes the direction from the description, so state it there too. - Type: String - Allowed values: `forward` (After the video), `backward` (Before the video) - Default: `"forward"` #### `image_urls` (Optional) Photo reference URLs: up to 30 in version 2.5, up to 9 in the 2.0 family. - Type: List (String, uri) - Maximum items: 30 #### `audio_urls` (Optional) Audio reference URLs: up to 10 in version 2.5, up to 3 in the 2.0 family. Audio only together with a photo or a video. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of a file (MP4, MOV): in version 2.5 up to 200 MB and no longer than 30 seconds, in the 2.0 family up to 50 MB and no longer than 15 seconds. At least 2 seconds, 24 to 60 frames per second and at least 407,696 pixels per frame (for example 640×640 or 480×854). - Pictures are URLs of JPEG, PNG, WEBP, BMP, TIFF, GIF files up to 30 MB each, sides from 300 to 6,000 pixels. - Audio files are URLs of WAV, MP3 files up to 15 MB each: in version 2.5 from 2 to 30 seconds and no longer than 30 all together, in the 2.0 family from 2 to 15 seconds and no longer than 15 all together. - The 2.0 family takes no more than 12 files of all kinds together. - The model takes the direction from the description: write that the video should be extended and what happens next, or for an extension backward write "extend backward" and what happened before the start. extend_direction only sets which side of your video we join the new part to. - On Channel 1 only version 2.5 can extend a video: for the 2.0 family choose Channel 2. - The video goes to the model as is and whole: to use another piece, trim the file beforehand. The seconds of your video are added to the length of the new part in the price, a part of a second counts as a whole one. On Channel 2 the price is not below a floor that grows with the length of the part. - We learn the video length for the price by downloading the video from its URL, so the URL must point straight at the file, without redirects, and serve it quickly. Otherwise the price cannot be calculated and the task is not accepted. - In the description your video is @video1, and photos and audio go in the order of their URLs: @image1, @audio1 and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4, mov | 1 | 200 MB | | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 MB | | `audio_urls` | Audio | wav, mp3 | 10 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. What happened next ```json { "model": "seedance", "settings": { "mode": "video_extend", "prompt": "Продли @video1: кораблик проплывает под мостиком и скрывается за поворотом", "video_urls": [ "https://example.com/boat.mp4" ], "duration": 5, "channel": "channel_2", "model": "seedance_2_mini" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP4 video. - Generation usually takes a few minutes, longer for long clips and high quality. - The new part comes first, then the same part joined with your video on the extend_direction side. The joined clip has the frame size of the new part, the sound of your video is kept. - If joining fails, only the new part comes, with an explanation in texts. The price is the same: the part is ready. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | The new part. | | `video` | mp4 | 0 or 1 | Your video and the new part as one clip. Absent if joining fails. | `result.texts`: An explanation if joining fails. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Seedance 2.0 Mini: features and prices](https://api.cyhub.ai/models/seedance-2-mini) - Other versions: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Seedance 2.0 API](https://api.cyhub.ai/en/models/seedance-2/api.md), [Seedance 2.0 Fast API](https://api.cyhub.ai/en/models/seedance-2-fast/api.md) - Similar models: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Suno V6 API > Suno V6 songs and sounds from scratch by a description or your own lyrics: two MP3 variants of the track per run. From your audio: add vocals or music, a cover, a continuation, a rewritten part, a mashup of two tracks. Versions V6 Mini and V6 Wild are available too. Developer: Suno Model key in the API: `suno` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "suno", "settings": { "mode": "generate", "model": "V6", "customMode": false, "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "suno", "settings": { "mode": "generate", "model": "V6", "customMode": False, "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "suno", "settings": { "mode": "generate", "model": "V6", "customMode": false, "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "suno", "settings": { "mode": "generate", "model": "V6", "customMode": false, "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## A song from scratch > A song from a short description, or with your own lyrics, style and title. Value of the mode field: `generate` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model` (Optional) Model version. - Type: String - Allowed values: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild) - Default: `"V6"` #### `customMode` (Optional) Advanced mode: your own lyrics, style, title and duration. Off: a song description is enough. - Type: Boolean - Default: `false` #### `songDescription` (Optional) Song description for the simple mode: subject, mood, genre. Required when customMode is off. - Type: String - Maximum characters: 3000 #### `title` (Optional) Song title. Required in advanced mode, not set in simple mode. - Type: String - Maximum characters: 80 #### `style` (Optional) Style and genre in words. Required in advanced mode, not set in simple mode. - Type: String - Maximum characters: 1000 #### `prompt` (Optional) Lyrics for the advanced mode. Required unless the track is instrumental. Not set in simple mode: there the description defines the song. - Type: String - Maximum characters: 5000 #### `instrumental` (Optional) No vocals. - Type: Boolean - Default: `false` #### `vocalGender` (Optional) Singer voice, advanced mode only. - Type: String - Allowed values: `m`, `f` - Default: `"m"` #### `duration` (Optional) Duration in seconds, advanced mode only. - Type: Integer - Minimum: 10 - Maximum: 360 - Default: `20` #### `styleWeight` (Optional) How strictly to follow the given style: 0 loosely, 1 strictly, at most two decimals. Advanced mode only. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `weirdnessConstraint` (Optional) How bold the result is: 0 predictable, 1 experimental, at most two decimals. Advanced mode only. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `audioWeight` (Optional) Weight of the audio features in the result: 0 weak, 1 strong, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Simple mode: a song description, the model invents the rest. Title, style and lyrics are not set in it. - Advanced mode: title and style are required; lyrics are required unless the track is instrumental. - Voice, duration, style weight and weirdness work only in advanced mode: in simple mode they are not sent. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Song from a description ```json { "model": "suno", "settings": { "mode": "generate", "model": "V6", "customMode": false, "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал" } } ``` Song with your own lyrics ```json { "model": "suno", "settings": { "mode": "generate", "model": "V6", "customMode": true, "title": "Дорога к морю", "style": "акустический поп, лето", "prompt": "Куплет 1: ...\nПрипев: ...", "instrumental": false, "vocalGender": "f", "duration": 120 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Two MP3 versions of the track per run, plus the title and lyrics as text when there are any. - A song takes 5 to 10 minutes, a sound about a minute. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 2 | Two versions of the track. | `result.texts`: The title and lyrics of the song, when there are any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## A sound or ambience > Not a song but a sound: rain, city hum, a game effect. It can be looped, with a set tempo and key. Value of the mode field: `sounds` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model` (Optional) Model version. - Type: String - Allowed values: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild) - Default: `"V6"` #### `soundDescription` (Required) What it should sound like, for example rain on a roof or footsteps in snow. There will be no lyrics. - Type: String - Minimum characters: 1 - Maximum characters: 500 #### `soundLoop` (Optional) Make the end flow into the beginning without a click: for background that plays in a loop. - Type: Boolean - Default: `false` #### `soundTempo` (Optional) Tempo in beats per minute. Not set: the model chooses it. - Type: Integer - Minimum: 1 - Maximum: 300 #### `soundKey` (Optional) Key: a letter means major, a letter with m means minor (Am is A minor). An empty string: any. - Type: String - Allowed values: `""` (Any), `C`, `C#`, `D`, `D#`, `E`, `F`, `F#`, `G`, `G#`, `A`, `A#`, `B`, `Cm`, `C#m`, `Dm`, `D#m`, `Em`, `Fm`, `F#m`, `Gm`, `G#m`, `Am`, `A#m`, `Bm` - Default: `""` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Background for a video ```json { "model": "suno", "settings": { "mode": "sounds", "soundDescription": "Шум дождя по жестяной крыше, далёкие раскаты грома", "soundLoop": true } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Two MP3 versions of the track per run, plus the title and lyrics as text when there are any. - A song takes 5 to 10 minutes, a sound about a minute. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 2 | Two versions of the track. | `result.texts`: The title and lyrics of the song, when there are any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Add vocals > Vocals on top of your music without a voice: the model sings your lyrics in the given style. Value of the mode field: `add_vocals` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model` (Optional) Model version. - Type: String - Allowed values: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild) - Default: `"V6"` #### `audio` (Required) One URL of your music without vocals. - Type: List (String, uri) - Maximum items: 1 #### `title` (Required) Track title. Required. - Type: String - Minimum characters: 1 - Maximum characters: 80 #### `style` (Required) Style and genre in words. Required. - Type: String - Minimum characters: 1 - Maximum characters: 1000 #### `prompt` (Required) The lyrics the vocals will sing. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `negativeTags` (Required) Styles that must not appear in the result, comma separated. Required. - Type: String - Minimum characters: 1 - Maximum characters: 500 #### `vocalGender` (Optional) Singer gender: m male, f female. Only raises the chance, does not guarantee it. Not set: the model decides. - Type: String - Allowed values: `""` (Not set), `m`, `f` - Default: `""` #### `styleWeight` (Optional) How strictly to follow the given style: 0 loosely, 1 strictly, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `weirdnessConstraint` (Optional) How bold the result is: 0 predictable, 1 experimental, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `audioWeight` (Optional) How closely the result keeps the sound of the source: 0 loosely, 1 closely, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Audio is a URL of an MP3, WAV, OGG, M4A, FLAC or AAC file up to 20 MB. - Your own audio only: Suno recognises well-known songs by others and refuses them. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav, ogg, m4a, flac, aac | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Vocals on your music ```json { "model": "suno", "settings": { "mode": "add_vocals", "audio": [ "https://example.com/my-instrumental.mp3" ], "title": "Ночной город", "style": "синти-поп, мягкий женский вокал", "prompt": "Куплет 1: ...\nПрипев: ...", "negativeTags": "хеви-метал, рэп" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Two MP3 versions of the track per run, plus the title and lyrics as text when there are any. - A song takes 5 to 10 minutes, a sound about a minute. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 2 | Two versions of the track. | `result.texts`: The title and lyrics of the song, when there are any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Add instrumental > Music under your vocals recorded without accompaniment. Value of the mode field: `add_instrumental` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model` (Optional) Model version. - Type: String - Allowed values: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild) - Default: `"V6"` #### `audio` (Required) One URL of your vocals without music. - Type: List (String, uri) - Maximum items: 1 #### `title` (Required) Track title. Required. - Type: String - Minimum characters: 1 - Maximum characters: 80 #### `tags` (Required) Music style in words: genre, instruments, mood. Required. - Type: String - Minimum characters: 1 - Maximum characters: 500 #### `negativeTags` (Required) Styles that must not appear in the result, comma separated. Required. - Type: String - Minimum characters: 1 - Maximum characters: 500 #### `vocalGender` (Optional) Singer gender: m male, f female. Only raises the chance, does not guarantee it. Not set: the model decides. - Type: String - Allowed values: `""` (Not set), `m`, `f` - Default: `""` #### `styleWeight` (Optional) How strictly to follow the given style: 0 loosely, 1 strictly, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `weirdnessConstraint` (Optional) How bold the result is: 0 predictable, 1 experimental, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `audioWeight` (Optional) How closely the result keeps the sound of the source: 0 loosely, 1 closely, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Audio is a URL of an MP3, WAV, OGG, M4A, FLAC or AAC file up to 20 MB. - Your own audio only: Suno recognises well-known songs by others and refuses them. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav, ogg, m4a, flac, aac | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Music under your voice ```json { "model": "suno", "settings": { "mode": "add_instrumental", "audio": [ "https://example.com/my-vocals.mp3" ], "title": "Колыбельная", "tags": "нежное фортепиано, струнные", "negativeTags": "барабаны, электроника" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Two MP3 versions of the track per run, plus the title and lyrics as text when there are any. - A song takes 5 to 10 minutes, a sound about a minute. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 2 | Two versions of the track. | `result.texts`: The title and lyrics of the song, when there are any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## A cover of your audio > The melody of your track stays, the style changes. As with a song from scratch: from a description or with your own lyrics, style and title. Value of the mode field: `cover_upload` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model` (Optional) Model version. - Type: String - Allowed values: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild) - Default: `"V6"` #### `audio` (Required) One URL of your track. - Type: List (String, uri) - Maximum items: 1 #### `customMode` (Optional) Advanced mode: your own lyrics, style, title and duration. Off: a song description is enough. - Type: Boolean - Default: `false` #### `songDescription` (Optional) Song description for the simple mode: subject, mood, genre. Required when customMode is off. - Type: String - Maximum characters: 3000 #### `title` (Optional) Song title. Required in advanced mode, not set in simple mode. - Type: String - Maximum characters: 80 #### `style` (Optional) Style and genre in words. Required in advanced mode, not set in simple mode. - Type: String - Maximum characters: 1000 #### `prompt` (Optional) Lyrics for the advanced mode. Required unless the track is instrumental. Not set in simple mode: there the description defines the song. - Type: String - Maximum characters: 5000 #### `instrumental` (Optional) No vocals. - Type: Boolean - Default: `false` #### `negativeTags` (Optional) Styles that must not appear in the result, comma separated. Advanced mode only. - Type: String - Maximum characters: 500 #### `duration` (Optional) Duration in seconds, advanced mode only. - Type: Integer - Minimum: 10 - Maximum: 360 - Default: `20` #### `styleWeight` (Optional) How strictly to follow the given style: 0 loosely, 1 strictly, at most two decimals. Advanced mode only. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `weirdnessConstraint` (Optional) How bold the result is: 0 predictable, 1 experimental, at most two decimals. Advanced mode only. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `audioWeight` (Optional) How closely the result keeps the sound of the source: 0 loosely, 1 closely, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Audio is a URL of an MP3, WAV, OGG, M4A, FLAC or AAC file up to 20 MB. - Your own audio only: Suno recognises well-known songs by others and refuses them. - The track is at most 8 minutes long. - Simple mode: a song description, the model invents the rest. Title, style and lyrics are not set in it. - Advanced mode: title and style are required; lyrics are required unless the track is instrumental. - Duration, style weight and weirdness work only in advanced mode: in simple mode they are not sent. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav, ogg, m4a, flac, aac | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A cover in another style ```json { "model": "suno", "settings": { "mode": "cover_upload", "audio": [ "https://example.com/my-song.mp3" ], "customMode": false, "songDescription": "Та же мелодия в стиле лёгкого джаза, женский вокал" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Two MP3 versions of the track per run, plus the title and lyrics as text when there are any. - A song takes 5 to 10 minutes, a sound about a minute. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 2 | Two versions of the track. | `result.texts`: The title and lyrics of the song, when there are any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Continue your audio > The track continues from the chosen second. The continuation second is required, the style and title are optional: without them the continuation follows the track itself. Value of the mode field: `extend` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model` (Optional) Model version. - Type: String - Allowed values: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild) - Default: `"V6"` #### `audio` (Required) One URL of your track. - Type: List (String, uri) - Maximum items: 1 #### `title` (Optional) Track title. Optional. - Type: String - Maximum characters: 100 #### `style` (Optional) Style and genre in words. Optional. - Type: String - Maximum characters: 1000 #### `prompt` (Optional) Lyrics of the continuation. Required unless the continuation is instrumental. - Type: String - Maximum characters: 5000 #### `instrumental` (Optional) A continuation without vocals. - Type: Boolean - Default: `false` #### `continueAt` (Required) The second of the track where the continuation starts. Before the end of the file. - Type: Number - Minimum: 1 - Maximum: 480 #### `negativeTags` (Optional) Styles that must not appear in the result, comma separated. - Type: String - Maximum characters: 500 #### `vocalGender` (Optional) Singer gender: m male, f female. Only raises the chance, does not guarantee it. Not set: the model decides. - Type: String - Allowed values: `""` (Not set), `m`, `f` - Default: `""` #### `styleWeight` (Optional) How strictly to follow the given style: 0 loosely, 1 strictly, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `weirdnessConstraint` (Optional) How bold the result is: 0 predictable, 1 experimental, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `audioWeight` (Optional) How closely the result keeps the sound of the source: 0 loosely, 1 closely, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `defaultParamFlag` = `true` ### Input - Audio is a URL of an MP3, WAV, OGG, M4A, FLAC or AAC file up to 20 MB. - Your own audio only: Suno recognises well-known songs by others and refuses them. - The track is at most 8 minutes long. - The continuation second comes before the end of the track. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav, ogg, m4a, flac, aac | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Continue your track ```json { "model": "suno", "settings": { "mode": "extend", "audio": [ "https://example.com/my-song.mp3" ], "title": "Дорога к морю", "style": "акустический поп, лето", "prompt": "Куплет 3: ...\nПрипев: ...", "continueAt": 60 } } ``` Continue without lyrics, as the track sounds ```json { "model": "suno", "settings": { "mode": "extend", "audio": [ "https://example.com/my-song.mp3" ], "instrumental": true, "continueAt": 90 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Two MP3 versions of the track per run, plus the title and lyrics as text when there are any. - A song takes 5 to 10 minutes, a sound about a minute. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 2 | Two versions of the track. | `result.texts`: The title and lyrics of the song, when there are any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Rewrite a part of your audio > Only the chosen section of the track is rewritten, the rest stays and is stitched to the new part. Value of the mode field: `replace_upload` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model` (Optional) Model version. - Type: String - Allowed values: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild) - Default: `"V6"` #### `audio` (Required) One URL of your track. - Type: List (String, uri) - Maximum items: 1 #### `infillStartS` (Required) Start of the section in seconds, at most two decimals, for example 45.25. - Type: Number - Minimum: 0 #### `infillEndS` (Required) End of the section in seconds, at most two decimals. At least 10 seconds and at most half of the track. - Type: Number - Minimum: 0 #### `prompt` (Required) New lyrics for this section. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `fullLyrics` (Required) The whole lyrics, already with the changed section. If there are no lyrics, describe in order what sounds. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `tags` (Required) Style of the new section in words. Required. - Type: String - Minimum characters: 1 - Maximum characters: 500 #### `title` (Required) Track title. Required. - Type: String - Minimum characters: 1 - Maximum characters: 80 #### `negativeTags` (Optional) Styles that must not appear in the result, comma separated. - Type: String - Maximum characters: 500 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Audio is a URL of an MP3, WAV, OGG, M4A, FLAC or AAC file up to 20 MB. - Your own audio only: Suno recognises well-known songs by others and refuses them. - The section is at least 10 seconds and at most half of the track. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav, ogg, m4a, flac, aac | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A new chorus ```json { "model": "suno", "settings": { "mode": "replace_upload", "audio": [ "https://example.com/my-song.mp3" ], "infillStartS": 45, "infillEndS": 70, "prompt": "Новый припев: ...", "fullLyrics": "Куплет 1: ...\nНовый припев: ...\nКуплет 2: ...", "tags": "поп-рок, энергично", "title": "Дорога к морю" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Two MP3 versions of the track per run, plus the title and lyrics as text when there are any. - A song takes 5 to 10 minutes, a sound about a minute. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 2 | Two versions of the track. | `result.texts`: The title and lyrics of the song, when there are any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## A mashup of two tracks > Two of your tracks are mixed into one, the first sets the base. From a description or with your own lyrics, style and title. Value of the mode field: `mashup` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model` (Optional) Model version. - Type: String - Allowed values: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild) - Default: `"V6"` #### `audio` (Required) URL of the first track: it sets the base. - Type: List (String, uri) - Maximum items: 1 #### `audio2` (Required) URL of the second track. - Type: List (String, uri) - Maximum items: 1 #### `customMode` (Optional) Advanced mode: your own lyrics, style, title and duration. Off: a song description is enough. - Type: Boolean - Default: `false` #### `songDescription` (Optional) Song description for the simple mode: subject, mood, genre. Required when customMode is off. - Type: String - Maximum characters: 3000 #### `title` (Optional) Song title. Required in advanced mode, not set in simple mode. - Type: String - Maximum characters: 80 #### `style` (Optional) Style and genre in words. Required in advanced mode, not set in simple mode. - Type: String - Maximum characters: 1000 #### `prompt` (Optional) Lyrics for the advanced mode, optional. Not set in simple mode: there the description defines the song. - Type: String - Maximum characters: 5000 #### `instrumental` (Optional) No vocals. - Type: Boolean - Default: `false` #### `duration` (Optional) Duration in seconds, advanced mode only. - Type: Integer - Minimum: 10 - Maximum: 360 - Default: `20` #### `styleWeight` (Optional) How strictly to follow the given style: 0 loosely, 1 strictly, at most two decimals. Advanced mode only. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `weirdnessConstraint` (Optional) How bold the result is: 0 predictable, 1 experimental, at most two decimals. Advanced mode only. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` #### `audioWeight` (Optional) How closely the result keeps the sound of the source: 0 loosely, 1 closely, at most two decimals. - Type: Number - Minimum: 0.0 - Maximum: 1.0 - Default: `0.65` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Audio is a URL of an MP3, WAV, OGG, M4A, FLAC or AAC file up to 20 MB. - Your own audio only: Suno recognises well-known songs by others and refuses them. - Simple mode: a song description, the model invents the rest. Title, style and lyrics are not set in it. - Advanced mode: title and style are required, lyrics are optional. - Duration, style weight and weirdness work only in advanced mode: in simple mode they are not sent. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav, ogg, m4a, flac, aac | 1 | 20 MB | | `audio2` | Audio | mp3, wav, ogg, m4a, flac, aac | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A mashup from a description ```json { "model": "suno", "settings": { "mode": "mashup", "audio": [ "https://example.com/track-1.mp3" ], "audio2": [ "https://example.com/track-2.mp3" ], "customMode": false, "songDescription": "Танцевальный ремикс, быстрый темп, яркий припев" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Two MP3 versions of the track per run, plus the title and lyrics as text when there are any. - A song takes 5 to 10 minutes, a sound about a minute. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 2 | Two versions of the track. | `result.texts`: The title and lyrics of the song, when there are any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Suno V6: features and prices](https://api.cyhub.ai/models/suno) - Similar models: [Eleven Music API](https://api.cyhub.ai/en/models/eleven-music/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # GPT Image 2.5 API > GPT Image 2.5 images by OpenAI from a description and references (up to 16), up to 4K and with a transparent background. Two variants, Flare and Sunburst, with the same settings: thirteen aspect ratios and three quality steps. The prompt is required. Developer: OpenAI Model key in the API: `images_chatgpt` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "images_chatgpt", "settings": { "model": "gpt-image-2-5-sunburst", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1", "resolution": "2K" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "images_chatgpt", "settings": { "model": "gpt-image-2-5-sunburst", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1", "resolution": "2K", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "images_chatgpt", "settings": { "model": "gpt-image-2-5-sunburst", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1", "resolution": "2K" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "images_chatgpt", "settings": { "model": "gpt-image-2-5-sunburst", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1", "resolution": "2K" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## GPT Image 2.5 > Two variants of version 2.5 with the same settings: thirteen aspect ratios, up to 4K, three quality steps, transparent background, up to 16 references. The prompt is required. Value of the model field: `gpt-image-2-5-flare` `gpt-image-2-5-sunburst` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Required even with reference images. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `quality` (Optional) How carefully the model works the image out. Each next step costs more and takes longer, and it decides which aspect ratios are available. - Type: String - Allowed values: `high`, `xhigh` (Very high), `max` - Default: `"high"` #### `background` (Optional) Background: auto, transparent (PNG) or opaque. With a transparent background the price is counted differently and also depends on the number of references. - Type: String - Allowed values: `auto`, `transparent`, `opaque` - Default: `"auto"` #### `aspect_ratio` (Optional) Aspect ratio. The set depends on quality and background. - Type: String - Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `27:16`, `16:27`, `9:8`, `8:9` - The set depends on `quality`, `background`. - Exceptions: | `quality` | `background` | `aspect_ratio` | |---|---|---| | `high` | `auto`, `opaque` | plus `auto` | - Default: `"9:16"` #### `resolution` (Optional) Image resolution: 1K, 2K or 4K. The price depends on it. - Type: String - Allowed values: `1K`, `2K`, `4K` - The set depends on `quality`, `aspect_ratio`. - Exceptions: | `quality` | `aspect_ratio` | `resolution` | |---|---|---| | `high` | `27:16`, `16:27`, `9:8`, `8:9` | only `1K` | - Default: `"1K"` #### `image_urls` (Optional) Reference image URLs, up to 16. - Type: List (String, uri) - Maximum items: 16 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - References are URLs of JPEG, PNG or WebP images, up to 10 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 16 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Square image in 2K ```json { "model": "images_chatgpt", "settings": { "model": "gpt-image-2-5-sunburst", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1", "resolution": "2K" } } ``` Sticker without background ```json { "model": "images_chatgpt", "settings": { "model": "gpt-image-2-5-flare", "prompt": "Рыжий кот в очках, вырезать предмет, фон прозрачный", "aspect_ratio": "1:1", "resolution": "1K", "background": "transparent" } } ``` Maximum quality ```json { "model": "images_chatgpt", "settings": { "model": "gpt-image-2-5-sunburst", "prompt": "Витрина ювелирного магазина, отражения и блики на стекле", "aspect_ratio": "16:9", "resolution": "4K", "quality": "max" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One PNG image per run. - 4K takes noticeably longer, up to several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [GPT Image 2.5: features and prices](https://api.cyhub.ai/models/gpt-image-2-5) - Other versions: [GPT Image 2 API](https://api.cyhub.ai/en/models/gpt-image-2/api.md), [GPT Image 1.5 API](https://api.cyhub.ai/en/models/gpt-image-1-5/api.md) - Similar models: [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # GPT Image 2 API > GPT Image 2 images by OpenAI from a description and references (up to 14), up to 4K. Six aspect ratios, PNG output. The prompt may be empty when references are given. Developer: OpenAI Model key in the API: `images_chatgpt` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "images_chatgpt", "settings": { "model": "gpt-image-2", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "16:9", "resolution": "2K" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "images_chatgpt", "settings": { "model": "gpt-image-2", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "16:9", "resolution": "2K", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "images_chatgpt", "settings": { "model": "gpt-image-2", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "16:9", "resolution": "2K" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "images_chatgpt", "settings": { "model": "gpt-image-2", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "16:9", "resolution": "2K" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## GPT Image 2 > Six aspect ratios, up to 4K, up to 14 references. The prompt may be empty when references are given. Value of the model field: `gpt-image-2` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Optional) What to draw. May be empty when reference images are given. - Type: String - Maximum characters: 3000 #### `aspect_ratio` (Optional) Aspect ratio. - Type: String - Allowed values: `auto`, `1:1`, `9:16`, `16:9`, `4:3`, `3:4` - Default: `"9:16"` #### `resolution` (Optional) Image resolution: 1K, 2K or 4K. Some aspect ratios allow fewer resolutions. The price depends on it. - Type: String - Allowed values: `1K`, `2K`, `4K` - The set depends on `aspect_ratio`. - Exceptions: | `aspect_ratio` | `resolution` | |---|---| | `auto` | only `1K` | | `1:1` | except `4K` | - Default: `"1K"` #### `image_urls` (Optional) Reference image URLs, up to 14. - Type: List (String, uri) - Maximum items: 14 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - References are URLs of JPEG, PNG or WebP images, up to 10 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 14 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Wide image in 2K ```json { "model": "images_chatgpt", "settings": { "model": "gpt-image-2", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "16:9", "resolution": "2K" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One PNG image per run. - 4K takes noticeably longer, up to several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [GPT Image 2: features and prices](https://api.cyhub.ai/models/gpt-image-2) - Other versions: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [GPT Image 1.5 API](https://api.cyhub.ai/en/models/gpt-image-1-5/api.md) - Similar models: [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # GPT Image 1.5 API > GPT Image 1.5 images by OpenAI from a description and references (up to 14). Three aspect ratios and one resolution, PNG output. The prompt may be empty when references are given. Developer: OpenAI Model key in the API: `images_chatgpt` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "images_chatgpt", "settings": { "model": "gpt-image-1.5", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "images_chatgpt", "settings": { "model": "gpt-image-1.5", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "images_chatgpt", "settings": { "model": "gpt-image-1.5", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "images_chatgpt", "settings": { "model": "gpt-image-1.5", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## GPT Image 1.5 > Three aspect ratios, one resolution, up to 14 references. The prompt may be empty when references are given. Value of the model field: `gpt-image-1.5` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Optional) What to draw. May be empty when reference images are given. - Type: String - Maximum characters: 3000 #### `aspect_ratio` (Optional) Aspect ratio. - Type: String - Allowed values: `1:1`, `2:3`, `3:2` - Default: `"1:1"` #### `image_urls` (Optional) Reference image URLs, up to 14. - Type: List (String, uri) - Maximum items: 14 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - References are URLs of JPEG, PNG or WebP images, up to 10 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 14 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Square image ```json { "model": "images_chatgpt", "settings": { "model": "gpt-image-1.5", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "1:1" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One PNG image per run. - 4K takes noticeably longer, up to several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [GPT Image 1.5: features and prices](https://api.cyhub.ai/models/gpt-image-1-5) - Other versions: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [GPT Image 2 API](https://api.cyhub.ai/en/models/gpt-image-2/api.md) - Similar models: [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # ElevenLabs API > ElevenLabs voices: voiceover of text and dialogues with ready-made voices, voice change in your own recording and dubbing of a recording into another language. Developer: ElevenLabs Model key in the API: `elevenlabs` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "elevenlabs", "settings": { "mode": "text_to_dialogue", "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.", "voice": "cgSgspJ2msm6clMCkdW9", "language_code": "ru" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "elevenlabs", "settings": { "mode": "text_to_dialogue", "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.", "voice": "cgSgspJ2msm6clMCkdW9", "language_code": "ru", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "elevenlabs", "settings": { "mode": "text_to_dialogue", "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.", "voice": "cgSgspJ2msm6clMCkdW9", "language_code": "ru" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "elevenlabs", "settings": { "mode": "text_to_dialogue", "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.", "voice": "cgSgspJ2msm6clMCkdW9", "language_code": "ru" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Text to speech > The text is read by the chosen voice. For a dialogue, each line has its own text and voice. Value of the mode field: `text_to_dialogue` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `text` (Required) The text to voice. Delivery can be guided with tags in square brackets, for example [whispering] or [laughing]. In a dialogue this is the first line; the next ones go in text_2, text_3 and so on up to text_20, in order, without gaps, by the same rules. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `voice` (Required) The voice that reads the text (in a dialogue, the voice of the first line). Ready-made ElevenLabs voices, the label gives the name and character of the voice. Each next line has its own voice: voice_2 for text_2, voice_3 for text_3 and so on up to voice_20, with the same values as voice. - Type: String - Allowed values: `BIvP0GN1cAtSRTxNHnWS` (Ellen - Serious, Direct and Confident), `aMSt68OGf4xUZAnLpTU8` (Juniper - Grounded and Professional), `RILOU7YmBhvwJGDGjNmP` (Jane - Professional Audiobook Reader), `EkK5I93UQWFDigLMpZcX` (James - Husky, Engaging and Bold), `Z3R5wn05IrDiVCyEkUrK` (Arabella - Mysterious and Emotive), `tnSpp4vdxKPjI9w0GnoV` (Hope - upbeat and clear), `NNl6r8mD7vthiJatiJt1` (Bradford - Expressive and Articulate), `YOq2y2Up4RgXP2HyXjE5` (Xavier - Dominating, Metalic Announcer), `Bj9UqZbhQsanLzgalpEG` (Austin - Deep, Raspy and Authentic), `c6SfcYrb2t09NHXiT80T` (Jarnathan - Confident and Versatile), `B8gJV1IhpuegLxdpXFOE` (Kuon - Cheerful, Clear and Steady), `exsUS4vynmxd379XN4yO` (Blondie - Conversational), `BpjGufoPiobT79j2vtj4` (Priyanka - Calm, Neutral and Relaxed), `2zRM7PkgwBPiau2jvVXc` (Monika Sogam - Deep and Natural), `1SM7GgM6IMuvQlz2BwM3` (Mark - Casual, Relaxed and Light), `ouL9IsyrSnUkCmfnD02u` (Grimblewood Thornwhisker - Snarky Gnome & Magical Maintainer), `5l5f8iK3YPeGga21rQIX` (Adeline - Feminine and Conversational), `scOwDtmlUjD3prqpp97I` (Sam - Support Agent), `NOpBlnGInO9m6vDvFkFC` (Spuds Oxley - Wise and Approachable), `BZgkqPqms7Kj9ulSkVzn` (Eve - Authentic, Energetic and Happy), `wo6udizrrtpIxWGp2qJk` (Northern Terry), `yjJ45q8TVCrtMhEKurxY` (Dr. Von - Quirky, Mad Scientist), `gU0LNdkMOQCOrPrwtbee` (British Football Announcer), `DGzg6RaUqxGRTHSBjfgF` (Brock - Commanding and Loud Sergeant), `DGTOOUoGpoP6UZ9uSWfA` (Célian - Documentary Narrator), `x70vRnQBMBu4FAYhjJbO` (Nathan - Virtual Radio Host), `Sm1seazb4gs7RSlUVw7c` (Anika - Animated, Friendly and Engaging), `P1bg08DkjqiVEzOn76yG` (Viraj - Rich and Soft), `qDuRKMlYmrm8trt5QyBn` (Taksh - Calm, Serious and Smooth), `kUUTqKQ05NMGulF08DDf` (Guadeloupe Merryweather - Emotional), `qXpMhyvQqiRxWQs4qSSB` (Horatius - Energetic Character Voice), `TX3LPaxmHKxFdv7VOQHJ` (Liam - Energetic, Social Media Creator), `iP95p4xoKVk53GoZ742B` (Chris - Charming, Down-to-Earth), `SOYHLrjzK2X1ezoPC6cr` (Harry - Fierce Warrior), `N2lVS1w4EtoT3dr4eOWO` (Callum - Husky Trickster), `FGY2WhTYpPnrIDTdsKH5` (Laura - Enthusiast, Quirky Attitude), `XB0fDUnXU5powFXDhCwa` (Charlotte), `cgSgspJ2msm6clMCkdW9` (Jessica - Playful, Bright, Warm), `LG95yZDEHg6fCZdQjLqj` (Phil - Explosive, Passionate Announcer), `CeNX9CMwmxDxUF5Q2Inm` (Johnny Dynamite - Vintage Radio DJ), `st7NwhTPEzqo2riw7qWC` (Blondie - Radio Host), `aD6riP1btT197c6dACmy` (Rachel M - Pro British Radio Presenter), `FF7KdobWPaiR0vkcALHF` (David - Movie Trailer Narrator), `mtrellq69YZsNwzUSyXh` (Rex Thunder - Deep N Tough), `dHd5gvgSOzSfduK4CvEg` (Ed - Late Night Announcer), `cTNP6ZM2mLTKj2BFhxEh` (Paul French - Podcaster), `ZF6FPAbjXT4488VcRRnw` (Amelia - Enthusiastic and Expressive), `8JVbfL6oEdmuxKn5DK2C` (Johnny Kid - Serious and Calm Narrator), `iCrDUkL56s3C8sCRl7wb` (Hope - Poetic, Romantic and Captivating), `1hlpeD1ydbI2ow0Tt3EW` (Olivia - Smooth, Warm and Engaging), `wJqPPQ618aTW29mptyoc` (Ana Rita - Smooth, Expressive and Bright), `EiNlNiXeDU1pqqOPrYMO` (John Doe - Deep), `FUfBrNit0NNZAwb58KWH` (Angela - Conversational and Friendly), `4YYIPFl9wE5c4L2eu2Gb` (Burt Reynolds™ - Deep, Smooth and clear), `OYWwCdDHouzDwiZJWOOu` (David - Gruff Cowboy), `6F5Zhi321D3Oq7v1oNT4` (Hank - Deep and Engaging Narrator), `qNkzaJoHLLdpvgh5tISm` (Carter - Rich, Smooth and Rugged), `YXpFCvM1S3JbWEJhoskW` (Wyatt- Wise Rustic Cowboy), `KTPVrSVAEUSJRClDzBw7` (Bob - Rugged and Warm Cowboy), `9PVP7ENhDskL0KYHAKtD` (Jerry B. - Southern/Cowboy), `vfaqCOvlrKi4Zp7C2IAm` (Malyx - Echoey, Menacing and Deep Demon), `piI8Kku0DcvcL6TTSeQt` (Flicker - Cheerful Fairy & Sparkly Sweetness), `flHkNRp1BlvT73UL6gyz` (Jessica Anne Bogart - Eloquent Villain), `9yzdeviXkFddZ4Oz8Mok` (Lutz - Chuckling, Giggly and Cheerful), `pPdl9cQBQq4p6mRkZy2Z` (Emma - Adorable and Upbeat), `0SpgpJ4D3MpHCiWdyTg3` (Matthew Schmitz - Elitist, Arrogant, Conniving Tyrant), `UFO0Yv86wqRxAt1DmXUu` (Sarcastic and Sultry Villain), `oR4uRy4fHDUGGISL0Rev` (Myrrdin - Wise and Magical Narrator), `zYcjlYFOd3taleS0gkk3` (Edward - Loud, Confident and Cocky), `nzeAacJi50IvxcyDnMXa` (Marshal - Friendly, Funny Professor), `ruirxsoakN0GWmGNIo04` (John Morgan - Gritty, Rugged Cowboy), `1KFdM0QCwQn4rmn5nn9C` (Parasyte - Whispers from the Deep Dark), `TC0Zp7WVFzhA8zpTlRqV` (Aria - Sultry Villain), `ljo9gAlSqKOvF6D8sOsX` (Viking Bjorn - Epic Medieval Raider), `PPzYpIqttlTYA83688JI` (Pirate Marshal), `eVItLK1UvXctxuaRV2Oq` (Jean - Alluring and Playful Femme Fatale), `U1Vk2oyatMdYs096Ety7` (Michael - Deep, Dark and Urban), `esy0r39YPLQjOczyOib8` (Britney - Calm and Calculative Villain), `bwCXcoVxWNYMlC6Esa8u` (Matthew Schmitz - Gravel, Deep Anti-Hero), `D2jw4N9m4xePLTQ3IHjU` (Ian - Strange and Distorted Alien), `Tsns2HvNFKfGiNjllgqo` (Sven - Emotional and Nice), `MnUw1cSnpiLoLhpd3Hqp` (Heather Rey - Rushed and Friendly), `kPzsL2i3teMYv0FxEYQ6` (Brittney - Social Media Voice - Fun, Youthful & Informative), `UgBBYS2sOqTuMpoF3BR0` (Mark - Natural Conversations), `IjnA9kwZJHJ20Fp7Vmy6` (Matthew - Casual, Friendly and Smooth), `KoQQbl9zjAdLgKZjm8Ol` (Pro Narrator - Convincing story teller), `hpp4J3VqNfWAUOO0d1Us` (Bella - Professional, Bright, Warm), `pNInz6obpgDQGcFmaJgB` (Adam - Dominant, Firm), `nPczCjzI2devNBz1zQrb` (Brian - Deep, Resonant and Comforting), `Atp5cNFg1Wj5gyKD7HWV` (Natasha - Gentle Meditation), `1cxc5c3E9K6F1wlqOJGV` (Emily - Gentile, Soft and Meditative), `1U02n4nD6AdIZ9CjF053` (Viraj - Smooth and Gentle), `HgyIHe81F3nXywNwkraY` (Nate - Sultry, Whispery and Seductive), `AeRdCCKzvd23BpJoofzx` (Nathaniel - Engaging, British and Calm), `LruHrtVF6PSyGItzMNHS` (Benjamin - Deep, Warm, Calming), `Qggl4b0xRMiqOwhPtVWT` (Clara - Relaxing, Calm and Soothing), `zA6D7RyKdc2EClouEMkP` (AImee - Tranquil ASMR and Meditation), `1wGbFxmAM3Fgw63G1zZJ` (Allison - Calm, Soothing and Meditative), `hqfrgApggtO1785R4Fsn` (Theodore HQ - Serene and Grounded), `sH0WdfE5fsKuM2otdQZr` (Koraly - Soft-spoken and Gentle), `MJ0RnG71ty4LH3dvNfSd` (Leon - Soothing and Grounded), `L0Dsvb3SLTyegXwtm47J` (Archer), `uYXf8XasLslADfZ2MB4u` (Hope - Bubbly, Gossipy and Girly), `gs0tAILXbY5DNrJrsM6F` (Jeff - Classy, Resonating and Strong), `DTKMou8ccj1ZaWGBiotd` (Jamahal - Young, Vibrant, and Natural), `vBKc2FfBKJfcZNyEt1n6` (Finn - Youthful, Eager and Energetic), `TmNe0cCqkZBMwPWOd3RD` (Smith - Mellow, Spontaneous, and Bassy), `DYkrAHD8iwork3YSUBbs` (Tom - Conversations & Books), `56AoDkrOh6qfVPDXZ7Pt` (Cassidy - Crisp, Direct and Clear), `eR40ATw9ArzDf9h3v7t7` (Addison 2.0 - Australian Audiobook & Podcast), `g6xIsTj2HwM6VR4iXFCw` (Jessica Anne Bogart - Chatty and Friendly), `lcMyyd2HUfFzxdCaC4Ta` (Lucy - Fresh & Casual), `6aDn1KB0hjpdcocrUkmq` (Tiffany - Natural and Welcoming), `Sq93GQT4X1lKDXsQcixO` (Felix - Warm, positive & contemporary RP) #### `tts_version` (Optional) Model version. v4 is new: it follows emotions from tags in square brackets more closely and knows more languages. v3 is the previous one: voices sound as in earlier voice-overs, on v4 they may sound slightly different. - Type: String - Allowed values: `v4`, `v3` - Default: `"v4"` #### `stability` (Optional) How even the voice sounds: 0 is more expressive but less predictable, 0.5 is balanced, 1 is even and predictable. - Type: String - Allowed values: `0` (Dynamic), `0.5` (Balanced), `1` (Stable) - Default: `"0.5"` #### `language_code` (Optional) Voiceover language. auto: detected from the text. Setting the language of the text explicitly works better. The list depends on the version: v4 has more. - Type: String - Allowed values: `auto`, `ru`, `en`, `af`, `ar`, `hy`, `as`, `az`, `be`, `bn`, `bs`, `bg`, `ca`, `ceb`, `ny`, `hr`, `cs`, `da`, `nl`, `et`, `fil`, `fi`, `fr`, `gl`, `ka`, `de`, `el`, `gu`, `ha`, `he`, `hi`, `hu`, `is`, `id`, `ga`, `it`, `ja`, `jv`, `kn`, `kk`, `ky`, `ko`, `lv`, `ln`, `lt`, `lb`, `mk`, `ms`, `ml`, `zh`, `mr`, `ne`, `no`, `ps`, `fa`, `pl`, `pt`, `pa`, `ro`, `sr`, `sd`, `sk`, `sl`, `so`, `es`, `sw`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`, `cy` - The set depends on `tts_version`. - Exceptions: | `tts_version` | `language_code` | |---|---| | `v4` | plus `ast`, `my`, `yue`, `mt`, `mi`, `mn`, `oc`, `or`, `tg`, `uz`, `yo` | - Default: `"auto"` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Up to 20 lines and up to 5000 characters in the whole text, up to 10 different voices. - ElevenLabs voices up to 2,000 characters at a time reliably: a longer text may stop short or fail, better split it into several runs. - The price follows the number of characters in the text and the voices: the owners of some voices in the ElevenLabs library charge extra for them, so characters in such a voice cost more. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A text read by one voice ```json { "model": "elevenlabs", "settings": { "mode": "text_to_dialogue", "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.", "voice": "cgSgspJ2msm6clMCkdW9", "language_code": "ru" } } ``` A dialogue of two voices ```json { "model": "elevenlabs", "settings": { "mode": "text_to_dialogue", "text": "[cheerfully] Привет! Ты уже видел новый парк у реки?", "voice": "cgSgspJ2msm6clMCkdW9", "text_2": "[curious] Ещё нет. Там правда так красиво?", "voice_2": "iP95p4xoKVk53GoZ742B", "stability": "0.5", "language_code": "ru" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP3 file with the voiceover. - The voiceover takes from a few seconds to a minute depending on the text length. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` | mp3 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Voice change > The same recording in a different voice: intonation, pauses and tempo stay as in the source. Audio or video up to 5 minutes. Value of the mode field: `voice_change` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `audio_url` (Optional) URL of the audio to change the voice in. Either this or video_url is needed. - Type: List (String, uri) - Maximum items: 1 #### `video_url` (Optional) URL of the video to change the voice in: the same video comes back with the new voice. Either this or audio_url is needed. - Type: List (String, uri) - Maximum items: 1 #### `voice` (Required) The voice the recording will sound in. Ready-made ElevenLabs voices, the label gives the name and character of the voice. - Type: String - Allowed values: `BIvP0GN1cAtSRTxNHnWS` (Ellen - Serious, Direct and Confident), `aMSt68OGf4xUZAnLpTU8` (Juniper - Grounded and Professional), `RILOU7YmBhvwJGDGjNmP` (Jane - Professional Audiobook Reader), `EkK5I93UQWFDigLMpZcX` (James - Husky, Engaging and Bold), `Z3R5wn05IrDiVCyEkUrK` (Arabella - Mysterious and Emotive), `tnSpp4vdxKPjI9w0GnoV` (Hope - upbeat and clear), `NNl6r8mD7vthiJatiJt1` (Bradford - Expressive and Articulate), `YOq2y2Up4RgXP2HyXjE5` (Xavier - Dominating, Metalic Announcer), `Bj9UqZbhQsanLzgalpEG` (Austin - Deep, Raspy and Authentic), `c6SfcYrb2t09NHXiT80T` (Jarnathan - Confident and Versatile), `B8gJV1IhpuegLxdpXFOE` (Kuon - Cheerful, Clear and Steady), `exsUS4vynmxd379XN4yO` (Blondie - Conversational), `BpjGufoPiobT79j2vtj4` (Priyanka - Calm, Neutral and Relaxed), `2zRM7PkgwBPiau2jvVXc` (Monika Sogam - Deep and Natural), `1SM7GgM6IMuvQlz2BwM3` (Mark - Casual, Relaxed and Light), `ouL9IsyrSnUkCmfnD02u` (Grimblewood Thornwhisker - Snarky Gnome & Magical Maintainer), `5l5f8iK3YPeGga21rQIX` (Adeline - Feminine and Conversational), `scOwDtmlUjD3prqpp97I` (Sam - Support Agent), `NOpBlnGInO9m6vDvFkFC` (Spuds Oxley - Wise and Approachable), `BZgkqPqms7Kj9ulSkVzn` (Eve - Authentic, Energetic and Happy), `wo6udizrrtpIxWGp2qJk` (Northern Terry), `yjJ45q8TVCrtMhEKurxY` (Dr. Von - Quirky, Mad Scientist), `gU0LNdkMOQCOrPrwtbee` (British Football Announcer), `DGzg6RaUqxGRTHSBjfgF` (Brock - Commanding and Loud Sergeant), `DGTOOUoGpoP6UZ9uSWfA` (Célian - Documentary Narrator), `x70vRnQBMBu4FAYhjJbO` (Nathan - Virtual Radio Host), `Sm1seazb4gs7RSlUVw7c` (Anika - Animated, Friendly and Engaging), `P1bg08DkjqiVEzOn76yG` (Viraj - Rich and Soft), `qDuRKMlYmrm8trt5QyBn` (Taksh - Calm, Serious and Smooth), `kUUTqKQ05NMGulF08DDf` (Guadeloupe Merryweather - Emotional), `qXpMhyvQqiRxWQs4qSSB` (Horatius - Energetic Character Voice), `TX3LPaxmHKxFdv7VOQHJ` (Liam - Energetic, Social Media Creator), `iP95p4xoKVk53GoZ742B` (Chris - Charming, Down-to-Earth), `SOYHLrjzK2X1ezoPC6cr` (Harry - Fierce Warrior), `N2lVS1w4EtoT3dr4eOWO` (Callum - Husky Trickster), `FGY2WhTYpPnrIDTdsKH5` (Laura - Enthusiast, Quirky Attitude), `XB0fDUnXU5powFXDhCwa` (Charlotte), `cgSgspJ2msm6clMCkdW9` (Jessica - Playful, Bright, Warm), `LG95yZDEHg6fCZdQjLqj` (Phil - Explosive, Passionate Announcer), `CeNX9CMwmxDxUF5Q2Inm` (Johnny Dynamite - Vintage Radio DJ), `st7NwhTPEzqo2riw7qWC` (Blondie - Radio Host), `aD6riP1btT197c6dACmy` (Rachel M - Pro British Radio Presenter), `FF7KdobWPaiR0vkcALHF` (David - Movie Trailer Narrator), `mtrellq69YZsNwzUSyXh` (Rex Thunder - Deep N Tough), `dHd5gvgSOzSfduK4CvEg` (Ed - Late Night Announcer), `cTNP6ZM2mLTKj2BFhxEh` (Paul French - Podcaster), `ZF6FPAbjXT4488VcRRnw` (Amelia - Enthusiastic and Expressive), `8JVbfL6oEdmuxKn5DK2C` (Johnny Kid - Serious and Calm Narrator), `iCrDUkL56s3C8sCRl7wb` (Hope - Poetic, Romantic and Captivating), `1hlpeD1ydbI2ow0Tt3EW` (Olivia - Smooth, Warm and Engaging), `wJqPPQ618aTW29mptyoc` (Ana Rita - Smooth, Expressive and Bright), `EiNlNiXeDU1pqqOPrYMO` (John Doe - Deep), `FUfBrNit0NNZAwb58KWH` (Angela - Conversational and Friendly), `4YYIPFl9wE5c4L2eu2Gb` (Burt Reynolds™ - Deep, Smooth and clear), `OYWwCdDHouzDwiZJWOOu` (David - Gruff Cowboy), `6F5Zhi321D3Oq7v1oNT4` (Hank - Deep and Engaging Narrator), `qNkzaJoHLLdpvgh5tISm` (Carter - Rich, Smooth and Rugged), `YXpFCvM1S3JbWEJhoskW` (Wyatt- Wise Rustic Cowboy), `KTPVrSVAEUSJRClDzBw7` (Bob - Rugged and Warm Cowboy), `9PVP7ENhDskL0KYHAKtD` (Jerry B. - Southern/Cowboy), `vfaqCOvlrKi4Zp7C2IAm` (Malyx - Echoey, Menacing and Deep Demon), `piI8Kku0DcvcL6TTSeQt` (Flicker - Cheerful Fairy & Sparkly Sweetness), `flHkNRp1BlvT73UL6gyz` (Jessica Anne Bogart - Eloquent Villain), `9yzdeviXkFddZ4Oz8Mok` (Lutz - Chuckling, Giggly and Cheerful), `pPdl9cQBQq4p6mRkZy2Z` (Emma - Adorable and Upbeat), `0SpgpJ4D3MpHCiWdyTg3` (Matthew Schmitz - Elitist, Arrogant, Conniving Tyrant), `UFO0Yv86wqRxAt1DmXUu` (Sarcastic and Sultry Villain), `oR4uRy4fHDUGGISL0Rev` (Myrrdin - Wise and Magical Narrator), `zYcjlYFOd3taleS0gkk3` (Edward - Loud, Confident and Cocky), `nzeAacJi50IvxcyDnMXa` (Marshal - Friendly, Funny Professor), `ruirxsoakN0GWmGNIo04` (John Morgan - Gritty, Rugged Cowboy), `1KFdM0QCwQn4rmn5nn9C` (Parasyte - Whispers from the Deep Dark), `TC0Zp7WVFzhA8zpTlRqV` (Aria - Sultry Villain), `ljo9gAlSqKOvF6D8sOsX` (Viking Bjorn - Epic Medieval Raider), `PPzYpIqttlTYA83688JI` (Pirate Marshal), `eVItLK1UvXctxuaRV2Oq` (Jean - Alluring and Playful Femme Fatale), `U1Vk2oyatMdYs096Ety7` (Michael - Deep, Dark and Urban), `esy0r39YPLQjOczyOib8` (Britney - Calm and Calculative Villain), `bwCXcoVxWNYMlC6Esa8u` (Matthew Schmitz - Gravel, Deep Anti-Hero), `D2jw4N9m4xePLTQ3IHjU` (Ian - Strange and Distorted Alien), `Tsns2HvNFKfGiNjllgqo` (Sven - Emotional and Nice), `MnUw1cSnpiLoLhpd3Hqp` (Heather Rey - Rushed and Friendly), `kPzsL2i3teMYv0FxEYQ6` (Brittney - Social Media Voice - Fun, Youthful & Informative), `UgBBYS2sOqTuMpoF3BR0` (Mark - Natural Conversations), `IjnA9kwZJHJ20Fp7Vmy6` (Matthew - Casual, Friendly and Smooth), `KoQQbl9zjAdLgKZjm8Ol` (Pro Narrator - Convincing story teller), `hpp4J3VqNfWAUOO0d1Us` (Bella - Professional, Bright, Warm), `pNInz6obpgDQGcFmaJgB` (Adam - Dominant, Firm), `nPczCjzI2devNBz1zQrb` (Brian - Deep, Resonant and Comforting), `Atp5cNFg1Wj5gyKD7HWV` (Natasha - Gentle Meditation), `1cxc5c3E9K6F1wlqOJGV` (Emily - Gentile, Soft and Meditative), `1U02n4nD6AdIZ9CjF053` (Viraj - Smooth and Gentle), `HgyIHe81F3nXywNwkraY` (Nate - Sultry, Whispery and Seductive), `AeRdCCKzvd23BpJoofzx` (Nathaniel - Engaging, British and Calm), `LruHrtVF6PSyGItzMNHS` (Benjamin - Deep, Warm, Calming), `Qggl4b0xRMiqOwhPtVWT` (Clara - Relaxing, Calm and Soothing), `zA6D7RyKdc2EClouEMkP` (AImee - Tranquil ASMR and Meditation), `1wGbFxmAM3Fgw63G1zZJ` (Allison - Calm, Soothing and Meditative), `hqfrgApggtO1785R4Fsn` (Theodore HQ - Serene and Grounded), `sH0WdfE5fsKuM2otdQZr` (Koraly - Soft-spoken and Gentle), `MJ0RnG71ty4LH3dvNfSd` (Leon - Soothing and Grounded), `L0Dsvb3SLTyegXwtm47J` (Archer), `uYXf8XasLslADfZ2MB4u` (Hope - Bubbly, Gossipy and Girly), `gs0tAILXbY5DNrJrsM6F` (Jeff - Classy, Resonating and Strong), `DTKMou8ccj1ZaWGBiotd` (Jamahal - Young, Vibrant, and Natural), `vBKc2FfBKJfcZNyEt1n6` (Finn - Youthful, Eager and Energetic), `TmNe0cCqkZBMwPWOd3RD` (Smith - Mellow, Spontaneous, and Bassy), `DYkrAHD8iwork3YSUBbs` (Tom - Conversations & Books), `56AoDkrOh6qfVPDXZ7Pt` (Cassidy - Crisp, Direct and Clear), `eR40ATw9ArzDf9h3v7t7` (Addison 2.0 - Australian Audiobook & Podcast), `g6xIsTj2HwM6VR4iXFCw` (Jessica Anne Bogart - Chatty and Friendly), `lcMyyd2HUfFzxdCaC4Ta` (Lucy - Fresh & Casual), `6aDn1KB0hjpdcocrUkmq` (Tiffany - Natural and Welcoming), `Sq93GQT4X1lKDXsQcixO` (Felix - Warm, positive & contemporary RP) Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The file is sent as a URL, exactly one: audio (mp3, wav, m4a, ogg, oga, flac) up to 20 MB in audio_url or video (mp4, mov, webm, mkv) up to 100 MB in video_url. The video must have a sound track. - A URL without an extension works too, for example a file of an earlier generation: the format is recognized from the file itself. - For the price, the server measures the length of the recording from the file itself, downloading it from the URL, and waits only a short time: a large file on a slow server may not download in time, then the price cannot be calculated and the request is refused. Large files need a URL on a fast server. - The URL must return the same file until the generation ends: the file is downloaded again at start, and if it turns out different, the generation may not start. - A recording up to 5 minutes: that is what ElevenLabs changes in one go. The price follows the length of the recording, per minute, and the voice: the owners of some voices in the ElevenLabs library charge extra for them, so a minute in such a voice costs more. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio_url` | Audio | mp3, wav, m4a, ogg, oga, flac | 1 | 20 MB | | `video_url` | Video | mp4, mov, webm, mkv | 1 | 100 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A different voice in a recording ```json { "model": "elevenlabs", "settings": { "mode": "voice_change", "audio_url": [ "https://example.com/voice.mp3" ], "voice": "iP95p4xoKVk53GoZ742B" } } ``` A different voice in a video ```json { "model": "elevenlabs", "settings": { "mode": "voice_change", "video_url": [ "https://example.com/clip.mp4" ], "voice": "cgSgspJ2msm6clMCkdW9" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - MP3 audio, or for a video input, the same video with the new voice. - The voice change takes up to a minute depending on the length of the recording. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` or `video` | mp3, mp4 | 1 | Audio for audio_url, video for video_url. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Dubbing into another language > The speech in a recording is translated into another language and voiced in similar voices. Audio or video up to 30 minutes. Value of the mode field: `dubbing` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `audio_url` (Optional) URL of the audio to translate. Either this or video_url is needed. - Type: List (String, uri) - Maximum items: 1 #### `video_url` (Optional) URL of the video to translate: the same video comes back with the translated speech. Either this or audio_url is needed. - Type: List (String, uri) - Maximum items: 1 #### `dubbing_version` (Optional) Dubbing version. v1 is cheaper and has fine-grained settings. v2 costs more, translates and voices more accurately and knows dialects, but ElevenLabs calls it an alpha version: rough edges are possible. - Type: String - Allowed values: `v1`, `v2` - Default: `"v1"` #### `dubbing_target_lang` (Required) The language the recording is translated and voiced into. The list depends on the version: v2 has dialects but lacks some rare v1 languages. - Type: String - Allowed values: `ru`, `en`, `ar`, `bg`, `hr`, `cs`, `da`, `nl`, `fil`, `fi`, `fr`, `de`, `el`, `hi`, `hu`, `id`, `it`, `ja`, `ko`, `ms`, `zh`, `no`, `pl`, `pt`, `ro`, `sk`, `es`, `sv`, `ta`, `tr`, `uk`, `vi` - The set depends on `dubbing_version`. - Exceptions: | `dubbing_version` | `dubbing_target_lang` | |---|---| | `v2` | plus `en-US`, `en-GB`, `en-AU`, `en-CA`, `af`, `ak`, `sq`, `am`, `ar-EG`, `hy`, `as`, `az`, `eu`, `be`, `bs`, `my`, `yue`, `ca`, `ceb`, `zh-TW`, `cmn`, `dgo`, `et`, `fr-FR`, `fr-CA`, `gl`, `ka`, `gu`, `ha`, `he`, `is`, `jv`, `kn`, `kk`, `ki`, `rw`, `rn`, `ky`, `lv`, `lt`, `lg`, `mk`, `ml`, `mr`, `mn`, `ne`, `fa`, `pt-BR`, `pt-PT`, `pa`, `nso`, `st`, `sd`, `sl`, `es-ES`, `es-MX`, `es-AR`, `es-CL`, `su`, `sw`, `ss`, `tg`, `te`, `th`, `bo`, `ts`, `tn`, `ur`, `ug`, `uz`, `ve`, `war`, `cy`, `wo`, `yo`, `zu` | #### `dubbing_source_lang` (Optional) Original language. auto: ElevenLabs detects it. - Type: String - Allowed values: `auto`, `ru`, `en`, `af`, `ar`, `hy`, `as`, `az`, `be`, `bn`, `bs`, `bg`, `ca`, `ceb`, `ny`, `hr`, `cs`, `da`, `nl`, `et`, `fil`, `fi`, `fr`, `gl`, `ka`, `de`, `el`, `gu`, `ha`, `he`, `hi`, `hu`, `is`, `id`, `ga`, `it`, `ja`, `jv`, `kn`, `kk`, `ky`, `ko`, `lv`, `ln`, `lt`, `lb`, `mk`, `ms`, `ml`, `zh`, `mr`, `ne`, `no`, `ps`, `fa`, `pl`, `pt`, `pa`, `ro`, `sr`, `sd`, `sk`, `sl`, `so`, `es`, `sw`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`, `cy` - The set depends on `dubbing_version`. - Exceptions: | `dubbing_version` | `dubbing_source_lang` | |---|---| | `v2` | `auto`, `ru`, `en`, `af`, `ak`, `sq`, `am`, `ar`, `hy`, `as`, `az`, `eu`, `be`, `bs`, `bg`, `my`, `yue`, `ca`, `ceb`, `zh`, `cmn`, `hr`, `cs`, `da`, `dgo`, `nl`, `et`, `fil`, `fi`, `fr`, `gl`, `ka`, `de`, `el`, `gu`, `ha`, `he`, `hi`, `hu`, `is`, `id`, `it`, `ja`, `jv`, `kn`, `kk`, `ki`, `rw`, `rn`, `ko`, `ky`, `lv`, `lt`, `lg`, `mk`, `ms`, `ml`, `mr`, `mn`, `ne`, `no`, `fa`, `pl`, `pt`, `pa`, `ro`, `nso`, `st`, `sd`, `sk`, `sl`, `es`, `su`, `sw`, `ss`, `sv`, `tg`, `ta`, `te`, `th`, `bo`, `ts`, `tn`, `tr`, `uk`, `ur`, `ug`, `uz`, `ve`, `vi`, `war`, `cy`, `wo`, `yo`, `zu` | - Default: `"auto"` #### `dubbing_num_speakers` (Optional) How many different voices are in the recording. 0: detect automatically. v1 only. - Type: Integer - Minimum: 0 - Maximum: 9 - Default: `0` #### `dubbing_drop_background_audio` (Optional) Remove music and background sounds, keep only the translated speech. For lectures and interviews, not for music videos. v1 only. - Type: Boolean - Default: `false` #### `dubbing_disable_voice_cloning` (Optional) Do not copy the timbre of the original voice, take a similar voice from the ElevenLabs library instead. Helps with noisy recordings. v1 only. - Type: Boolean - Default: `false` #### `dubbing_use_profanity_filter` (Optional) Replace profanity with [censored]. It may miss a word or trigger by mistake. v1 only. - Type: Boolean - Default: `false` #### `dubbing_highest_resolution` (Optional) Keep the original video resolution, processing takes a bit longer. Video only. v1 only. - Type: Boolean - Default: `false` #### `dubbing_target_accent` (Optional) An accent hint for the voiceover, for example british or american. It may be ignored. v1 only. - Type: String Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The file is sent as a URL, exactly one: audio (mp3, wav, m4a, ogg, oga, flac) up to 50 MB in audio_url or video (mp4, mov, webm, mkv) up to 500 MB in video_url. The video must have a sound track. - A URL without an extension works too, for example a file of an earlier generation: the format is recognized from the file itself. - For the price, the server measures the length of the recording from the file itself, downloading it from the URL, and waits only a short time: a large file on a slow server may not download in time, then the price cannot be calculated and the request is refused. Large files need a URL on a fast server. - The URL must return the same file until the generation ends: the file is downloaded again at start, and if it turns out different, the generation may not start. - A recording up to 30 minutes, the whole recording is dubbed. The price follows the length of the recording, per minute, v2 costs more. - Fine-grained settings (number of voices, background, cloning, profanity filter, resolution, accent) exist only in v1: with v2 a request with them is refused. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio_url` | Audio | mp3, wav, m4a, ogg, oga, flac | 1 | 50 MB | | `video_url` | Video | mp4, mov, webm, mkv | 1 | 500 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A video into English ```json { "model": "elevenlabs", "settings": { "mode": "dubbing", "video_url": [ "https://example.com/lecture.mp4" ], "dubbing_target_lang": "en" } } ``` An interview into Mexican Spanish, v2 ```json { "model": "elevenlabs", "settings": { "mode": "dubbing", "audio_url": [ "https://example.com/interview.mp3" ], "dubbing_version": "v2", "dubbing_target_lang": "es-MX", "dubbing_source_lang": "ru" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - An audio track in the new language, or for a video input, the same video with the translated speech. - Dubbing takes 1 to 15 minutes depending on the length of the recording. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` or `video` | mp3, mp4 | 1 | Audio for audio_url, video for video_url. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [ElevenLabs: features and prices](https://api.cyhub.ai/models/elevenlabs) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Nano Banana Pro API > Nano Banana Pro images by Google from a description and edits of your pictures: up to 8 references, quality up to 4K. Ten aspect ratios, PNG or JPG output. Developer: Google Model key in the API: `banana_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "banana_pro", "settings": { "model": "nano-banana-pro", "prompt": "Маяк на скале в шторм, кинематографичный свет", "size": "16:9", "resolution": "2K" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "banana_pro", "settings": { "model": "nano-banana-pro", "prompt": "Маяк на скале в шторм, кинематографичный свет", "size": "16:9", "resolution": "2K", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "banana_pro", "settings": { "model": "nano-banana-pro", "prompt": "Маяк на скале в шторм, кинематографичный свет", "size": "16:9", "resolution": "2K" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "banana_pro", "settings": { "model": "nano-banana-pro", "prompt": "Маяк на скале в шторм, кинематографичный свет", "size": "16:9", "resolution": "2K" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Nano Banana Pro > The high-quality version: ten aspect ratios, up to 4K, up to 8 references. Value of the model field: `nano-banana-pro` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw, or what to do with the reference images. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `resolution` (Optional) Quality: 1K, 2K or 4K. The price depends on it. - Type: String - Allowed values: `1K`, `2K`, `4K` - Default: `"1K"` #### `output_format` (Optional) Result file format. - Type: String - Allowed values: `png`, `jpg` - Default: `"png"` #### `google_search` (Optional) Banana 2 only: let the model search Google when it needs current facts or real places. - Type: Boolean - Default: `false` #### `size` (Optional) Aspect ratio. - Type: String - Allowed values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` - Default: `"1:1"` #### `image_urls` (Optional) Reference image URLs, up to 8. - Type: List (String, uri) - Maximum items: 8 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - References are URLs of JPEG, PNG or WebP images, up to 30 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 8 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Image from a prompt ```json { "model": "banana_pro", "settings": { "model": "nano-banana-pro", "prompt": "Маяк на скале в шторм, кинематографичный свет", "size": "16:9", "resolution": "2K" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One image per run in the chosen format. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg | 1 | The format is set by output_format. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Nano Banana Pro: features and prices](https://api.cyhub.ai/models/nano-banana-pro) - Other versions: [Nano Banana 2.1 API](https://api.cyhub.ai/en/models/nano-banana-2-1/api.md), [Nano Banana 2 API](https://api.cyhub.ai/en/models/nano-banana-2/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Nano Banana 2.1 API > Nano Banana 2.1 images by Google from a description and edits of your pictures: up to 10 references, quality up to 4K. Fourteen aspect ratios, including the elongated 1:4, 4:1, 1:8 and 8:1, plus auto, PNG or JPG output. Developer: Google Model key in the API: `banana_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "banana_pro", "settings": { "model": "nano-banana-2-1", "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»", "size": "3:4", "resolution": "2K" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "banana_pro", "settings": { "model": "nano-banana-2-1", "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»", "size": "3:4", "resolution": "2K", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "banana_pro", "settings": { "model": "nano-banana-2-1", "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»", "size": "3:4", "resolution": "2K" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "banana_pro", "settings": { "model": "nano-banana-2-1", "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»", "size": "3:4", "resolution": "2K" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Nano Banana 2.1 > The newest version and the default: fourteen aspect ratios, including the elongated 1:4, 4:1, 1:8 and 8:1, plus auto, up to 4K, up to 10 references. Value of the model field: `nano-banana-2-1` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw, or what to do with the reference images. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `resolution` (Optional) Quality: 1K, 2K or 4K. The price depends on it. - Type: String - Allowed values: `1K`, `2K`, `4K` - Default: `"1K"` #### `output_format` (Optional) Result file format. - Type: String - Allowed values: `png`, `jpg` - Default: `"png"` #### `google_search` (Optional) Banana 2 only: let the model search Google when it needs current facts or real places. - Type: Boolean - Default: `false` #### `size` (Optional) Aspect ratio. auto: the model picks it, with a reference usually the same as the reference. - Type: String - Allowed values: `auto`, `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9` - Default: `"1:1"` #### `image_urls` (Optional) Reference image URLs, up to 10. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - References are URLs of JPEG, PNG or WebP images, up to 30 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 10 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Poster with lettering ```json { "model": "banana_pro", "settings": { "model": "nano-banana-2-1", "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»", "size": "3:4", "resolution": "2K" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One image per run in the chosen format. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg | 1 | The format is set by output_format. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Nano Banana 2.1: features and prices](https://api.cyhub.ai/models/nano-banana-2-1) - Other versions: [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 API](https://api.cyhub.ai/en/models/nano-banana-2/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Nano Banana 2 API > Nano Banana 2 images by Google with a wide choice of aspect ratios, including the elongated 1:4, 4:1, 1:8 and 8:1. From a description and edits of your pictures (up to 10 references), quality up to 4K. You can let the model search Google for current facts and real places. Developer: Google Model key in the API: `banana_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "banana_pro", "settings": { "model": "nano-banana-2", "prompt": "Горный хребет на рассвете, туман в долинах", "size": "21:9", "resolution": "2K" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "banana_pro", "settings": { "model": "nano-banana-2", "prompt": "Горный хребет на рассвете, туман в долинах", "size": "21:9", "resolution": "2K", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "banana_pro", "settings": { "model": "nano-banana-2", "prompt": "Горный хребет на рассвете, туман в долинах", "size": "21:9", "resolution": "2K" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "banana_pro", "settings": { "model": "nano-banana-2", "prompt": "Горный хребет на рассвете, туман в долинах", "size": "21:9", "resolution": "2K" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Nano Banana 2 > The version with a wide choice of aspect ratios, including the elongated 1:4, 4:1, 1:8 and 8:1, and up to 10 references. Value of the model field: `nano-banana-2` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw, or what to do with the reference images. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `resolution` (Optional) Quality: 1K, 2K or 4K. The price depends on it. - Type: String - Allowed values: `1K`, `2K`, `4K` - Default: `"1K"` #### `output_format` (Optional) Result file format. - Type: String - Allowed values: `png`, `jpg` - Default: `"png"` #### `google_search` (Optional) Banana 2 only: let the model search Google when it needs current facts or real places. - Type: Boolean - Default: `false` #### `size` (Optional) Aspect ratio. - Type: String - Allowed values: `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9` - Default: `"1:1"` #### `image_urls` (Optional) Reference image URLs, up to 10. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - References are URLs of JPEG, PNG or WebP images, up to 30 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 10 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Wide banner ```json { "model": "banana_pro", "settings": { "model": "nano-banana-2", "prompt": "Горный хребет на рассвете, туман в долинах", "size": "21:9", "resolution": "2K" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One image per run in the chosen format. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg | 1 | The format is set by output_format. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Simplified call: model banana > Banana 2 images from a description, optionally with reference images: photo editing, style changes, one scene made from several photos. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw, or what to do with the reference images. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `image_urls` (Optional) Reference image URLs, up to 10. Without them the image is made from the description only. - Type: List (String, uri) - Maximum items: 10 #### `aspect_ratio` (Optional) Aspect ratio. adaptive: the model picks it itself, from the description or the reference image. - Type: String - Allowed values: `adaptive`, `1:1`, `9:16`, `3:4`, `4:3`, `16:9` - Default: `"adaptive"` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Reference images are URLs of JPEG, PNG or WebP files, up to 10 MB each. The link must open without signing in and without a redirect. If an image does not fit, the task ends with an error and no money is charged. - The aspect ratio is set by aspect_ratio: 1:1, 9:16, 3:4, 4:3 or 16:9. The default is adaptive: the model picks the aspect ratio itself, from the description or the reference image, and you can describe it in words in the description: "vertical", "horizontal" or "square". | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 10 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Image from a prompt ```json { "model": "banana", "settings": { "prompt": "Маяк на скале в шторм, кинематографичный свет", "aspect_ratio": "16:9" } } ``` Editing your own image ```json { "model": "banana", "settings": { "prompt": "Посади этого кота на подоконник, за окном дождь", "image_urls": [ "https://example.com/cat.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One image per run. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Nano Banana 2: features and prices](https://api.cyhub.ai/models/nano-banana-2) - Other versions: [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2.1 API](https://api.cyhub.ai/en/models/nano-banana-2-1/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Nano Banana 2 Lite API > Fast Banana 2 Lite images from a description, optionally with reference images to edit or follow. Always 1K resolution. Developer: Google Model key in the API: `banana2_lite` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "banana2_lite", "settings": { "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон", "size": "16:9" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "banana2_lite", "settings": { "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон", "size": "16:9", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "banana2_lite", "settings": { "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон", "size": "16:9" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "banana2_lite", "settings": { "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон", "size": "16:9" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Parameters Model parameters go inside settings. Omitted optional fields take their default values. ### `prompt` (Required) What to draw, or what to do with the reference images. - Type: String - Minimum characters: 1 - Maximum characters: 5000 ### `size` (Optional) Aspect ratio. Auto: the model picks it itself. - Type: String - Allowed values: `auto`, `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9` - Default: `"9:16"` ### `image_urls` (Optional) Reference image URLs, up to 10. Without them the image is made from the description only. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. ## Input - Reference images are URLs of JPEG, PNG or WebP files, up to 30 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 10 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ## Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Image from a prompt ```json { "model": "banana2_lite", "settings": { "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон", "size": "16:9" } } ``` Editing your own image ```json { "model": "banana2_lite", "settings": { "prompt": "Замени фон на летний луг, человека оставь как есть", "size": "auto", "image_urls": [ "https://example.com/photo.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ## Output - One image per run, 1K resolution. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Nano Banana 2 Lite: features and prices](https://api.cyhub.ai/models/nano-banana-2-lite) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Kling 3.0 API > Kling 3.0 video from a description or from the first and last frames: 3 to 15 seconds, up to 4K, with audio. The video can be split into several scenes, the model divides the description itself. Developer: Kuaishou Model key in the API: `kling_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v3.0", "prompt": "Лиса бежит по заснеженному лесу, камера движется следом", "quality": "1080p", "length": 8, "aspect_ratio": "16:9" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "kling_pro", "settings": { "model_version": "v3.0", "prompt": "Лиса бежит по заснеженному лесу, камера движется следом", "quality": "1080p", "length": 8, "aspect_ratio": "16:9", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "kling_pro", "settings": { "model_version": "v3.0", "prompt": "Лиса бежит по заснеженному лесу, камера движется следом", "quality": "1080p", "length": 8, "aspect_ratio": "16:9" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v3.0", "prompt": "Лиса бежит по заснеженному лесу, камера движется следом", "quality": "1080p", "length": 8, "aspect_ratio": "16:9" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Kling 3.0 > The newest version: 3 to 15 seconds, up to 4K, audio, splitting into scenes, first and last frame. Value of the model_version field: `v3.0` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the action, the camera movement, the mood of the scene. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `start_frame` (Optional) One URL of the picture the video starts from. - Type: List (String, uri) - Maximum items: 1 #### `end_frame` (Optional) One URL of the picture the video ends with. Works without a first frame too. - Type: List (String, uri) - Maximum items: 1 #### `quality` (Optional) Quality: 720p, 1080p or 4K. The price depends on it. - Type: String - Allowed values: `720p`, `1080p`, `4K` - Default: `"720p"` #### `length` (Optional) Video length in seconds, 3 to 15. The price grows with every second. - Type: Integer - Minimum: 3 - Maximum: 15 - Default: `5` #### `aspect_ratio` (Optional) Aspect ratio of a video without frames. With a first or last frame, the video takes the aspect ratio of the frame. - Type: String - Allowed values: `16:9`, `1:1`, `9:16` - Default: `"16:9"` #### `native_audio` (Optional) Audio: a soundtrack that matches the video, with voices, sounds and music. Costs more. - Type: Boolean - Default: `true` #### `multi_shot` (Optional) Split the video into several scenes: the model divides the description into scenes itself. It helps to describe the scenes in order in the description. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `api_request` = `true` ### Input - Frames are URLs of JPG or PNG files up to 10 MB: each side at least 300 pixels, aspect ratio from 1:2.5 to 2.5:1. - We download the frames ourselves: the link must open without signing in and lead straight to the file, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `start_frame` | Images | jpeg, jpg, png | 1 | 10 MB | | `end_frame` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a description ```json { "model": "kling_pro", "settings": { "model_version": "v3.0", "prompt": "Лиса бежит по заснеженному лесу, камера движется следом", "quality": "1080p", "length": 8, "aspect_ratio": "16:9" } } ``` From the first frame to the last ```json { "model": "kling_pro", "settings": { "model_version": "v3.0", "prompt": "Бутон медленно раскрывается в цветок", "start_frame": [ "https://example.com/bud.jpg" ], "end_frame": [ "https://example.com/flower.jpg" ], "length": 5, "native_audio": false } } ``` Several scenes ```json { "model": "kling_pro", "settings": { "model_version": "v3.0", "prompt": "Сначала мальчик находит на чердаке старую карту. Потом он бежит с ней через поле к маяку.", "multi_shot": true, "length": 12 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, with sound if it is on. - Generation usually takes 3-5 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Kling 3.0: features and prices](https://api.cyhub.ai/models/kling-3) - Other versions: [Kling 2.6 API](https://api.cyhub.ai/en/models/kling-2-6/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/en/models/kling-2-5-turbo/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/en/models/kling-2-1-master/api.md), [Kling 2.1 API](https://api.cyhub.ai/en/models/kling-2-1/api.md), [Kling 1.6 API](https://api.cyhub.ai/en/models/kling-1-6/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Kling 2.6 API > Kling 2.6 video with audio: voices, sounds and music for the video. From a description or from the first and last frames, 5 or 10 seconds, 720p or 1080p. Developer: Kuaishou Model key in the API: `kling_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v2.6", "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается", "start_frame": [ "https://example.com/host.png" ], "length": 5 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "kling_pro", "settings": { "model_version": "v2.6", "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается", "start_frame": [ "https://example.com/host.png", ], "length": 5, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "kling_pro", "settings": { "model_version": "v2.6", "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается", "start_frame": [ "https://example.com/host.png" ], "length": 5 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v2.6", "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается", "start_frame": [ "https://example.com/host.png" ], "length": 5 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Kling 2.6 > The version with audio: voices, sounds and music for the video. 5 or 10 seconds. Value of the model_version field: `v2.6` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the action, the camera movement, the mood of the scene. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `start_frame` (Optional) One URL of the picture the video starts from. - Type: List (String, uri) - Maximum items: 1 #### `end_frame` (Optional) One URL of the picture the video ends with. Only together with a first frame and without audio. - Type: List (String, uri) - Maximum items: 1 #### `quality` (Optional) Quality: 720p or 1080p, the price depends on it. With audio or a last frame, only 1080p. - Type: String - Allowed values: `720p`, `1080p` - Default: `"1080p"` #### `length` (Optional) Video length: 5 or 10 seconds. 10 seconds cost twice as much. - Type: Integer - Minimum: 5 - Maximum: 10 - Default: `5` #### `aspect_ratio` (Optional) Aspect ratio of a video without frames. With a first or last frame, the video takes the aspect ratio of the frame. - Type: String - Allowed values: `16:9`, `1:1`, `9:16` - Default: `"16:9"` #### `native_audio` (Optional) Audio: a soundtrack that matches the video, with voices, sounds and music. Costs more. Only in 1080p and without a last frame. - Type: Boolean - Default: `true` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `api_request` = `true` ### Input - Frames are URLs of JPG or PNG files up to 10 MB: each side at least 300 pixels, aspect ratio from 1:2.5 to 2.5:1. - We download the frames ourselves: the link must open without signing in and lead straight to the file, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `start_frame` | Images | jpeg, jpg, png | 1 | 10 MB | | `end_frame` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a picture with sound ```json { "model": "kling_pro", "settings": { "model_version": "v2.6", "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается", "start_frame": [ "https://example.com/host.png" ], "length": 5 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, with sound if it is on. - Generation usually takes 3-5 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Kling 2.6: features and prices](https://api.cyhub.ai/models/kling-2-6) - Other versions: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/en/models/kling-2-5-turbo/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/en/models/kling-2-1-master/api.md), [Kling 2.1 API](https://api.cyhub.ai/en/models/kling-2-1/api.md), [Kling 1.6 API](https://api.cyhub.ai/en/models/kling-1-6/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Kling 2.5 Turbo API > Kling 2.5 Turbo video: a fast version with realistic physics and sound effects. From a description or from the first and last frames, 5 or 10 seconds, 720p or 1080p. Developer: Kuaishou Model key in the API: `kling_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v2.5t", "prompt": "Машина проезжает мимо камеры и скрывается за поворотом", "start_frame": [ "https://example.com/start.jpg" ], "end_frame": [ "https://example.com/end.jpg" ], "quality": "1080p" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "kling_pro", "settings": { "model_version": "v2.5t", "prompt": "Машина проезжает мимо камеры и скрывается за поворотом", "start_frame": [ "https://example.com/start.jpg", ], "end_frame": [ "https://example.com/end.jpg", ], "quality": "1080p", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "kling_pro", "settings": { "model_version": "v2.5t", "prompt": "Машина проезжает мимо камеры и скрывается за поворотом", "start_frame": [ "https://example.com/start.jpg" ], "end_frame": [ "https://example.com/end.jpg" ], "quality": "1080p" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v2.5t", "prompt": "Машина проезжает мимо камеры и скрывается за поворотом", "start_frame": [ "https://example.com/start.jpg" ], "end_frame": [ "https://example.com/end.jpg" ], "quality": "1080p" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Kling 2.5 Turbo > A fast version with realistic physics, 5 or 10 seconds, sound effects. Value of the model_version field: `v2.5t` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the action, the camera movement, the mood of the scene. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `start_frame` (Optional) One URL of the picture the video starts from. - Type: List (String, uri) - Maximum items: 1 #### `end_frame` (Optional) One URL of the picture the video ends with. Only together with a first frame. - Type: List (String, uri) - Maximum items: 1 #### `quality` (Optional) Quality: 720p or 1080p, the price depends on it. With a last frame, only 1080p. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `length` (Optional) Video length: 5 or 10 seconds. 10 seconds cost twice as much. - Type: Integer - Minimum: 5 - Maximum: 10 - Default: `5` #### `aspect_ratio` (Optional) Aspect ratio of a video without frames. With a first or last frame, the video takes the aspect ratio of the frame. - Type: String - Allowed values: `16:9`, `1:1`, `9:16` - Default: `"16:9"` #### `sound_effects` (Optional) Sound effects in sync with the video. They do not work with a last frame. - Type: Boolean - Default: `false` #### `sfx_sound` (Optional) What sounds are needed, for example the sound of waves. Only with sound effects. - Type: String - Maximum characters: 200 #### `sfx_music` (Optional) What background music is needed, for example a melodic flute. Only with sound effects. - Type: String - Maximum characters: 200 #### `sfx_asmr` (Optional) ASMR mode: more detailed, immersive sounds. Only with sound effects. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `api_request` = `true`, `native_audio` = `false` ### Input - Frames are URLs of JPG or PNG files up to 10 MB: each side at least 300 pixels, aspect ratio from 1:2.5 to 2.5:1. - We download the frames ourselves: the link must open without signing in and lead straight to the file, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `start_frame` | Images | jpeg, jpg, png | 1 | 10 MB | | `end_frame` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. First and last frame ```json { "model": "kling_pro", "settings": { "model_version": "v2.5t", "prompt": "Машина проезжает мимо камеры и скрывается за поворотом", "start_frame": [ "https://example.com/start.jpg" ], "end_frame": [ "https://example.com/end.jpg" ], "quality": "1080p" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, with sound if it is on. - Generation usually takes 3-5 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Kling 2.5 Turbo: features and prices](https://api.cyhub.ai/models/kling-2-5-turbo) - Other versions: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling 2.6 API](https://api.cyhub.ai/en/models/kling-2-6/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/en/models/kling-2-1-master/api.md), [Kling 2.1 API](https://api.cyhub.ai/en/models/kling-2-1/api.md), [Kling 1.6 API](https://api.cyhub.ai/en/models/kling-1-6/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Kling 2.1 Master API > Kling 2.1 Master video with cinematic motion and sound effects, 1080p only. From a description or from your picture, 5 or 10 seconds, no last frame. Developer: Kuaishou Model key in the API: `kling_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v2.1m", "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах", "aspect_ratio": "9:16" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "kling_pro", "settings": { "model_version": "v2.1m", "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах", "aspect_ratio": "9:16", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "kling_pro", "settings": { "model_version": "v2.1m", "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах", "aspect_ratio": "9:16" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v2.1m", "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах", "aspect_ratio": "9:16" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Kling 2.1 Master > Cinematic motion, 1080p only, no last frame, 5 or 10 seconds. Value of the model_version field: `v2.1m` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the action, the camera movement, the mood of the scene. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `start_frame` (Optional) One URL of the picture the video starts from. - Type: List (String, uri) - Maximum items: 1 #### `quality` (Optional) This version makes video only in 1080p. - Type: String - Allowed values: `1080p` - Default: `"1080p"` #### `length` (Optional) Video length: 5 or 10 seconds. 10 seconds cost twice as much. - Type: Integer - Minimum: 5 - Maximum: 10 - Default: `5` #### `aspect_ratio` (Optional) Aspect ratio of a video without frames. With a first or last frame, the video takes the aspect ratio of the frame. - Type: String - Allowed values: `16:9`, `1:1`, `9:16` - Default: `"16:9"` #### `sound_effects` (Optional) Sound effects in sync with the video. They do not work with a last frame. - Type: Boolean - Default: `false` #### `sfx_sound` (Optional) What sounds are needed, for example the sound of waves. Only with sound effects. - Type: String - Maximum characters: 200 #### `sfx_music` (Optional) What background music is needed, for example a melodic flute. Only with sound effects. - Type: String - Maximum characters: 200 #### `sfx_asmr` (Optional) ASMR mode: more detailed, immersive sounds. Only with sound effects. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `api_request` = `true`, `native_audio` = `false` ### Input - Frames are URLs of JPG or PNG files up to 10 MB: each side at least 300 pixels, aspect ratio from 1:2.5 to 2.5:1. - We download the frames ourselves: the link must open without signing in and lead straight to the file, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `start_frame` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a description ```json { "model": "kling_pro", "settings": { "model_version": "v2.1m", "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах", "aspect_ratio": "9:16" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, with sound if it is on. - Generation usually takes 3-5 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Kling 2.1 Master: features and prices](https://api.cyhub.ai/models/kling-2-1-master) - Other versions: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling 2.6 API](https://api.cyhub.ai/en/models/kling-2-6/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/en/models/kling-2-5-turbo/api.md), [Kling 2.1 API](https://api.cyhub.ai/en/models/kling-2-1/api.md), [Kling 1.6 API](https://api.cyhub.ai/en/models/kling-1-6/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Kling 2.1 API > Kling 2.1 video from your picture: the first frame is required, a last frame can be added. 5 or 10 seconds, 720p or 1080p, sound effects. Developer: Kuaishou Model key in the API: `kling_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v2.1", "prompt": "Девушка поворачивается к камере и смеётся", "start_frame": [ "https://example.com/portrait.jpg" ] } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "kling_pro", "settings": { "model_version": "v2.1", "prompt": "Девушка поворачивается к камере и смеётся", "start_frame": [ "https://example.com/portrait.jpg", ], }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "kling_pro", "settings": { "model_version": "v2.1", "prompt": "Девушка поворачивается к камере и смеётся", "start_frame": [ "https://example.com/portrait.jpg" ] } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v2.1", "prompt": "Девушка поворачивается к камере и смеётся", "start_frame": [ "https://example.com/portrait.jpg" ] } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Kling 2.1 > Animates a picture: video only from a first frame, 5 or 10 seconds, sound effects. Value of the model_version field: `v2.1` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the action, the camera movement, the mood of the scene. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `start_frame` (Required) One URL of the picture the video starts from. Required. - Type: List (String, uri) - Maximum items: 1 #### `end_frame` (Optional) One URL of the picture the video ends with. Only together with a first frame. - Type: List (String, uri) - Maximum items: 1 #### `quality` (Optional) Quality: 720p or 1080p, the price depends on it. With a last frame, only 1080p. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `length` (Optional) Video length: 5 or 10 seconds. 10 seconds cost twice as much. - Type: Integer - Minimum: 5 - Maximum: 10 - Default: `5` #### `sound_effects` (Optional) Sound effects in sync with the video. They do not work with a last frame. - Type: Boolean - Default: `false` #### `sfx_sound` (Optional) What sounds are needed, for example the sound of waves. Only with sound effects. - Type: String - Maximum characters: 200 #### `sfx_music` (Optional) What background music is needed, for example a melodic flute. Only with sound effects. - Type: String - Maximum characters: 200 #### `sfx_asmr` (Optional) ASMR mode: more detailed, immersive sounds. Only with sound effects. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `api_request` = `true`, `native_audio` = `false` ### Input - Frames are URLs of JPG or PNG files up to 10 MB: each side at least 300 pixels, aspect ratio from 1:2.5 to 2.5:1. - We download the frames ourselves: the link must open without signing in and lead straight to the file, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `start_frame` | Images | jpeg, jpg, png | 1 | 10 MB | | `end_frame` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a photo ```json { "model": "kling_pro", "settings": { "model_version": "v2.1", "prompt": "Девушка поворачивается к камере и смеётся", "start_frame": [ "https://example.com/portrait.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, with sound if it is on. - Generation usually takes 3-5 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Kling 2.1: features and prices](https://api.cyhub.ai/models/kling-2-1) - Other versions: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling 2.6 API](https://api.cyhub.ai/en/models/kling-2-6/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/en/models/kling-2-5-turbo/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/en/models/kling-2-1-master/api.md), [Kling 1.6 API](https://api.cyhub.ai/en/models/kling-1-6/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Kling 1.6 API > Kling 1.6 video: a stable version with expressive faces and sound effects. From a description or from the first and last frames, 5 or 10 seconds, 720p or 1080p. Developer: Kuaishou Model key in the API: `kling_pro` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v1.6", "prompt": "Волны накатывают на берег, над морем летают чайки", "sound_effects": true, "sfx_sound": "шум прибоя и крики чаек" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "kling_pro", "settings": { "model_version": "v1.6", "prompt": "Волны накатывают на берег, над морем летают чайки", "sound_effects": True, "sfx_sound": "шум прибоя и крики чаек", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "kling_pro", "settings": { "model_version": "v1.6", "prompt": "Волны накатывают на берег, над морем летают чайки", "sound_effects": true, "sfx_sound": "шум прибоя и крики чаек" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_pro", "settings": { "model_version": "v1.6", "prompt": "Волны накатывают на берег, над морем летают чайки", "sound_effects": true, "sfx_sound": "шум прибоя и крики чаек" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Kling 1.6 > A stable version with expressive faces, 5 or 10 seconds, sound effects. Value of the model_version field: `v1.6` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the action, the camera movement, the mood of the scene. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `start_frame` (Optional) One URL of the picture the video starts from. - Type: List (String, uri) - Maximum items: 1 #### `end_frame` (Optional) One URL of the picture the video ends with. Only together with a first frame. - Type: List (String, uri) - Maximum items: 1 #### `quality` (Optional) Quality: 720p or 1080p, the price depends on it. With a last frame, only 1080p. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `length` (Optional) Video length: 5 or 10 seconds. 10 seconds cost twice as much. - Type: Integer - Minimum: 5 - Maximum: 10 - Default: `5` #### `aspect_ratio` (Optional) Aspect ratio of a video without frames. With a first or last frame, the video takes the aspect ratio of the frame. - Type: String - Allowed values: `16:9`, `1:1`, `9:16` - Default: `"16:9"` #### `sound_effects` (Optional) Sound effects in sync with the video. They do not work with a last frame. - Type: Boolean - Default: `false` #### `sfx_sound` (Optional) What sounds are needed, for example the sound of waves. Only with sound effects. - Type: String - Maximum characters: 200 #### `sfx_music` (Optional) What background music is needed, for example a melodic flute. Only with sound effects. - Type: String - Maximum characters: 200 #### `sfx_asmr` (Optional) ASMR mode: more detailed, immersive sounds. Only with sound effects. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `api_request` = `true`, `native_audio` = `false` ### Input - Frames are URLs of JPG or PNG files up to 10 MB: each side at least 300 pixels, aspect ratio from 1:2.5 to 2.5:1. - We download the frames ourselves: the link must open without signing in and lead straight to the file, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `start_frame` | Images | jpeg, jpg, png | 1 | 10 MB | | `end_frame` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video with sound effects ```json { "model": "kling_pro", "settings": { "model_version": "v1.6", "prompt": "Волны накатывают на берег, над морем летают чайки", "sound_effects": true, "sfx_sound": "шум прибоя и крики чаек" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, with sound if it is on. - Generation usually takes 3-5 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Kling 1.6: features and prices](https://api.cyhub.ai/models/kling-1-6) - Other versions: [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling 2.6 API](https://api.cyhub.ai/en/models/kling-2-6/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/en/models/kling-2-5-turbo/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/en/models/kling-2-1-master/api.md), [Kling 2.1 API](https://api.cyhub.ai/en/models/kling-2-1/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Kling Motion 3.0 API > Kling Motion 3.0 video: the person from your photo repeats the movements from your video. Version 3.0 follows complex movements and the face more closely, 720p or 1080p. You can keep the sound of the motion video. Developer: Kuaishou Model key in the API: `kling_motion` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.png" ], "video_url": [ "https://example.com/moves.mov" ], "model_version": "3.0", "quality": "pro", "with_audio": false, "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.png", ], "video_url": [ "https://example.com/moves.mov", ], "model_version": "3.0", "quality": "pro", "with_audio": False, "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.png" ], "video_url": [ "https://example.com/moves.mov" ], "model_version": "3.0", "quality": "pro", "with_audio": false, "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.png" ], "video_url": [ "https://example.com/moves.mov" ], "model_version": "3.0", "quality": "pro", "with_audio": false, "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now This page is about Kling Motion 3.0: send model_version = 3.0. Without the model_version field the task runs on 2.6. ## Parameters Model parameters go inside settings. Omitted optional fields take their default values. ### `image_url` (Required) One link to a photo of the character. The head and the body are clearly visible and not covered. The character is framed like the person in the video: to the waist or whole. - Type: List (String, uri) - Maximum items: 1 ### `video_url` (Required) One link to the motion video: best with one person filmed in a single shot, without cuts or camera movement. The whole video goes to Kling. - Type: List (String, uri) - Maximum items: 1 ### `prompt` (Optional) Optional. The scene and the look. There is no need to describe the motion, it is taken from the video. - Type: String - Maximum characters: 2500 ### `model_version` (Optional) Model version. VIDEO 3.0 follows complex movements and the face more closely, VIDEO 2.6 is proven and costs less. - Type: String - Allowed values: `3.0` - Default: `"2.6"` ### `quality` (Optional) Resolution: Standard 720p or Pro 1080p. Pro costs more. - Type: String - Allowed values: `std` (Standard), `pro` - Default: `"std"` ### `orientation` (Optional) How the character is turned: like the person in the video (better for complex movements, video up to 30 seconds) or like in the photo (the frame of the photo, video up to 10 seconds). - Type: String - Allowed values: `video`, `image` - Default: `"video"` ### `with_audio` (Optional) Keep the sound of the motion video in the finished video. - Type: Boolean - Default: `true` Parameters not listed here are not accepted: the response is 422 unknown_setting. ## Input - The photo is a link to a JPEG or PNG file up to 10 MB: at least 300 pixels on each side, aspect ratio from 1:2.5 to 2.5:1. - The video is a link to an MP4 or MOV file up to 100 MB, sides from 340 to 3850 pixels. Length from 3 to 30 seconds, up to 10 with the orientation from the photo. - The price is per second of the motion video, counted over its whole length. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_url` | Images | jpeg, jpg, png | 1 | 10 MB | | `video_url` | Video | mp4, mov | 1 | 100 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ## Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. VIDEO 3.0 in 1080p, no sound, with a scene ```json { "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.png" ], "video_url": [ "https://example.com/moves.mov" ], "model_version": "3.0", "quality": "pro", "with_audio": false, "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ## Output - One MP4 video as long as the motion video. It can be shorter: Kling takes only the movements it recognized. - Generation takes 5-10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Kling Motion 3.0: features and prices](https://api.cyhub.ai/models/kling-motion) - Other versions: [Kling Motion 2.6 API](https://api.cyhub.ai/en/models/kling-motion-2-6/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Kling Motion 2.6 API > Kling Motion 2.6 video: the person from your photo repeats the movements from your video. A proven and cheaper version, 720p or 1080p. Developer: Kuaishou Model key in the API: `kling_motion` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.jpg" ], "video_url": [ "https://example.com/dance.mp4" ], "model_version": "2.6" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.jpg", ], "video_url": [ "https://example.com/dance.mp4", ], "model_version": "2.6", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.jpg" ], "video_url": [ "https://example.com/dance.mp4" ], "model_version": "2.6" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.jpg" ], "video_url": [ "https://example.com/dance.mp4" ], "model_version": "2.6" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Parameters Model parameters go inside settings. Omitted optional fields take their default values. ### `image_url` (Required) One link to a photo of the character. The head and the body are clearly visible and not covered. The character is framed like the person in the video: to the waist or whole. - Type: List (String, uri) - Maximum items: 1 ### `video_url` (Required) One link to the motion video: best with one person filmed in a single shot, without cuts or camera movement. The whole video goes to Kling. - Type: List (String, uri) - Maximum items: 1 ### `prompt` (Optional) Optional. The scene and the look. There is no need to describe the motion, it is taken from the video. - Type: String - Maximum characters: 2500 ### `model_version` (Optional) Model version. VIDEO 3.0 follows complex movements and the face more closely, VIDEO 2.6 is proven and costs less. - Type: String - Allowed values: `2.6` - Default: `"2.6"` ### `quality` (Optional) Resolution: Standard 720p or Pro 1080p. Pro costs more. - Type: String - Allowed values: `std` (Standard), `pro` - Default: `"std"` ### `orientation` (Optional) How the character is turned: like the person in the video (better for complex movements, video up to 30 seconds) or like in the photo (the frame of the photo, video up to 10 seconds). - Type: String - Allowed values: `video`, `image` - Default: `"video"` ### `with_audio` (Optional) Keep the sound of the motion video in the finished video. - Type: Boolean - Default: `true` Parameters not listed here are not accepted: the response is 422 unknown_setting. ## Input - The photo is a link to a JPEG or PNG file up to 10 MB: at least 300 pixels on each side, aspect ratio from 1:2.5 to 2.5:1. - The video is a link to an MP4 or MOV file up to 100 MB, sides from 340 to 3850 pixels. Length from 3 to 30 seconds, up to 10 with the orientation from the photo. - The price is per second of the motion video, counted over its whole length. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_url` | Images | jpeg, jpg, png | 1 | 10 MB | | `video_url` | Video | mp4, mov | 1 | 100 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ## Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Repeat a dance from a video ```json { "model": "kling_motion", "settings": { "image_url": [ "https://example.com/person.jpg" ], "video_url": [ "https://example.com/dance.mp4" ] } } ``` The frame of the photo, video up to 10 seconds ```json { "model": "kling_motion", "settings": { "image_url": [ "https://example.com/portrait.jpg" ], "video_url": [ "https://example.com/short-moves.mp4" ], "orientation": "image" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ## Output - One MP4 video as long as the motion video. It can be shorter: Kling takes only the movements it recognized. - Generation takes 5-10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Kling Motion 2.6: features and prices](https://api.cyhub.ai/models/kling-motion-2-6) - Other versions: [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Midjourney 8.2 API > Midjourney 8.2 images from a description and from your photos: moving a person or an object into a new scene, editing a photo with words. A grid of four variants, image prompts and style samples. The previous version 8.1 is available too. Developer: Midjourney Model key in the API: `midjourney` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "midjourney", "settings": { "version": "8.2", "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo", "aspect_ratio": "3:2", "speed": "fast", "stylization": 250 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "midjourney", "settings": { "version": "8.2", "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo", "aspect_ratio": "3:2", "speed": "fast", "stylization": 250, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "midjourney", "settings": { "version": "8.2", "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo", "aspect_ratio": "3:2", "speed": "fast", "stylization": 250 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "midjourney", "settings": { "version": "8.2", "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo", "aspect_ratio": "3:2", "speed": "fast", "stylization": 250 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Midjourney 8.2 > The main versions: 8.2 by default, 8.1 the previous one. They also move a person or an object from a photo into a new scene and edit a photo with words (edit_images), at the price of a regular image. Value of the version field: `8.2` `8.1` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Plain text only: Midjourney parameters (--ar, --v and others), links and options in curly braces are not accepted, there are fields for the settings and pictures. Versions 8.2 and 8.1 shorten a description longer than about 1000 characters before generating, version 7 takes the whole text. - Type: String - Minimum characters: 1 - Maximum characters: 6000 #### `aspect_ratio` (Optional) Aspect ratio: width and height as whole numbers with a colon, digits only and no spaces, for example 1:1, 16:9, 9:16, 4:5, 2:3, 21:9. - Type: String - Maximum characters: 11 - Default: `"1:1"` #### `speed` (Optional) Speed. Relaxed is cheaper but waits in a queue, Fast is quicker and costs more. The price depends on it. - Type: String - Allowed values: `relaxed`, `fast` - Default: `"relaxed"` #### `stylization` (Optional) How artistic: 0 sticks to the description, 1000 adds the most beauty but drifts from the description. Not set: 100. - Type: Integer - Minimum: 0 - Maximum: 1000 #### `chaos` (Optional) How different the four pictures are: 0 similar, 100 the most different. - Type: Integer - Minimum: 0 - Maximum: 100 #### `weirdness` (Optional) Weirdness: 0 an ordinary picture, 3000 surrealism and abstraction. - Type: Integer - Minimum: 0 - Maximum: 3000 #### `raw_mode` (Optional) Without Midjourney artistic processing: the result is closer to an ordinary photo. - Type: Boolean - Default: `false` #### `tile` (Optional) A seamless pattern that repeats in every direction: wallpapers, fabrics, backgrounds. - Type: Boolean - Default: `false` #### `seed` (Optional) The starting number. The same number and description give a similar result. Not set: random. - Type: Integer - Minimum: 0 - Maximum: 4294967295 #### `exclusions` (Optional) What must not be in the picture, words separated by commas, for example: text, people, blur. - Type: String - Maximum characters: 500 #### `image_prompts` (Optional) Image prompts: Midjourney takes the subject, composition and colors from them. Up to 4 URLs. - Type: List (String, uri) - Maximum items: 4 #### `iw` (Optional) Strength of the image prompts: 0 barely matter, 3 the strongest. Not set: 1. Works only together with image prompts. - Type: Number - Minimum: 0 - Maximum: 3 #### `style_ref_images` (Optional) Style samples: the manner, colors and mood carry over, but not the objects. Up to 3 URLs. - Type: List (String, uri) - Maximum items: 3 #### `sref_code` (Optional) A Midjourney style code, digits only, for example 123456789. Can go together with style samples. - Type: String #### `sw` (Optional) Style strength: 0 barely matters, 1000 the strongest. Not set: 100. Works only together with style samples or a style code. - Type: Integer - Minimum: 0 - Maximum: 1000 #### `enable_translation` (Optional) Translate the description into English before generating. If the translation fails or contains parameters, links or options in braces, the original description goes instead. - Type: Boolean - Default: `false` #### `edit_images` (Optional) Photos Midjourney draws a new picture from: it moves a person, a character or an object into a new scene, changes the clothes or the background, shows it from another side, puts several photos together in one scene. Say what to do in prompt. Up to 4 URLs. The proportions of the result come from aspect_ratio, not from the photos. Does not go together with tile. - Type: List (String, uri) - Maximum items: 4 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `plain_text` = `true`, `rework_button` = `false` ### Input - Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, a picture for the mask edit must be a PNG. A link must open without signing in and without redirects. - The description and exclusions are plain text only: no Midjourney parameters, links or options in curly braces. Settings and pictures are set with fields. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_prompts` | Images | jpeg, jpg, png, webp | 4 | 10 MB | | `style_ref_images` | Images | jpeg, jpg, png, webp | 3 | 10 MB | | `edit_images` | Images | jpeg, jpg, png, webp | 4 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. An image from a description ```json { "model": "midjourney", "settings": { "version": "8.2", "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo", "aspect_ratio": "3:2", "speed": "fast", "stylization": 250 } } ``` A description in Russian with translation ```json { "model": "midjourney", "settings": { "version": "8.2", "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город", "aspect_ratio": "4:5", "enable_translation": true, "exclusions": "text, watermark" } } ``` An image in the style of a sample ```json { "model": "midjourney", "settings": { "version": "8.2", "prompt": "A lighthouse on a cliff at dusk, waves crashing below", "aspect_ratio": "16:9", "style_ref_images": [ "https://example.com/style-sample.jpg" ], "sw": 300 } } ``` A person from a photo in a new scene ```json { "model": "midjourney", "settings": { "version": "8.2", "prompt": "Make this woman wear a red silk gown on a seaside terrace at sunset, full body", "aspect_ratio": "2:3", "raw_mode": true, "edit_images": [ "https://example.com/person.jpg" ] } } ``` Editing a photo with words ```json { "model": "midjourney", "settings": { "version": "8.2", "prompt": "Make the jacket yellow and turn the background into a snowy forest", "aspect_ratio": "4:5", "edit_images": [ "https://example.com/photo.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Four JPEG pictures per run, each as a separate file. - With Fast the result usually comes in about a minute, Relaxed waits in a queue longer. - Upscaling and variations of finished pictures are only available in the bot. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | jpg | 4 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" }, { "index": 2, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/2" }, { "index": 3, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/3" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Midjourney 8.2: features and prices](https://api.cyhub.ai/models/midjourney) - Other versions: [Midjourney Editor API](https://api.cyhub.ai/en/models/midjourney-editor/api.md), [Midjourney 7 API](https://api.cyhub.ai/en/models/midjourney-7/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Midjourney Editor API > Midjourney Editor edits your picture: Midjourney redraws the transparent areas of a PNG from the description. Remove something, replace the background or an object, extend the frame, and the rest stays as it was. Developer: Midjourney Model key in the API: `midjourney` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "midjourney", "settings": { "version": "edit", "prompt": "A sunny beach with palm trees and a turquoise sea", "image_url": [ "https://example.com/portrait-transparent-background.png" ], "speed": "fast" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "midjourney", "settings": { "version": "edit", "prompt": "A sunny beach with palm trees and a turquoise sea", "image_url": [ "https://example.com/portrait-transparent-background.png", ], "speed": "fast", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "midjourney", "settings": { "version": "edit", "prompt": "A sunny beach with palm trees and a turquoise sea", "image_url": [ "https://example.com/portrait-transparent-background.png" ], "speed": "fast" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "midjourney", "settings": { "version": "edit", "prompt": "A sunny beach with palm trees and a turquoise sea", "image_url": [ "https://example.com/portrait-transparent-background.png" ], "speed": "fast" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Midjourney Editor > Midjourney redraws the transparent areas of your picture from the description and leaves the rest as it was: remove something, replace the background or an object, extend the frame. The edit is done by version 8.2. Value of the version field: `edit` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What should appear in the transparent areas of the picture. Plain text only: Midjourney parameters (--ar, --v and others), links and options in curly braces are not accepted. - Type: String - Minimum characters: 1 - Maximum characters: 900 #### `image_url` (Required) One URL of the PNG picture to edit: Midjourney redraws the transparent areas from the description and leaves the rest as it was. The long side is up to 2048 pixels, both sides divide by 16. - Type: List (String, uri) - Maximum items: 1 #### `speed` (Optional) Speed. Relaxed is cheaper but waits in a queue, Fast is quicker and costs more. The price depends on it. - Type: String - Allowed values: `relaxed`, `fast` - Default: `"relaxed"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `plain_text` = `true`, `rework_button` = `false` ### Input - Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, a picture for the mask edit must be a PNG. A link must open without signing in and without redirects. - The description and exclusions are plain text only: no Midjourney parameters, links or options in curly braces. Settings and pictures are set with fields. - Midjourney draws the transparent areas of the picture anew from the description. To extend the frame, add transparent margins at the edges: the result has the proportions of the picture. - The picture goes to Midjourney as is, without adjustments: a PNG up to 2048 pixels on the long side, both sides divide by 16 evenly, for example 1024×1024, 1456×816 or 816×1456. Any other picture is refused and nothing is charged for it. - The price is the same as for an image from a description at the same speed. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_url` | Images | png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Replace the background ```json { "model": "midjourney", "settings": { "version": "edit", "prompt": "A sunny beach with palm trees and a turquoise sea", "image_url": [ "https://example.com/portrait-transparent-background.png" ], "speed": "fast" } } ``` Extend the frame ```json { "model": "midjourney", "settings": { "version": "edit", "prompt": "A wide mountain valley at sunrise, mist over the river", "image_url": [ "https://example.com/photo-with-transparent-margins.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Four JPEG pictures per run, each as a separate file. - With Fast the result usually comes in about a minute, Relaxed waits in a queue longer. - Upscaling and variations of finished pictures are only available in the bot. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | jpg | 4 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" }, { "index": 2, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/2" }, { "index": 3, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/3" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Midjourney Editor: features and prices](https://api.cyhub.ai/models/midjourney-editor) - Other versions: [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Midjourney 7 API](https://api.cyhub.ai/en/models/midjourney-7/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Midjourney 7 API > Midjourney 7 images from a description and moving a person, a character or an object from a photo into a new picture. A grid of four variants, image prompts and style samples. A run with such a transfer costs more than a regular one. Developer: Midjourney Model key in the API: `midjourney` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "midjourney", "settings": { "version": "7", "prompt": "This man as an astronaut walking on the Moon, cinematic light", "aspect_ratio": "2:3", "omni_ref_image": [ "https://example.com/person.jpg" ], "ow": 200 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "midjourney", "settings": { "version": "7", "prompt": "This man as an astronaut walking on the Moon, cinematic light", "aspect_ratio": "2:3", "omni_ref_image": [ "https://example.com/person.jpg", ], "ow": 200, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "midjourney", "settings": { "version": "7", "prompt": "This man as an astronaut walking on the Moon, cinematic light", "aspect_ratio": "2:3", "omni_ref_image": [ "https://example.com/person.jpg" ], "ow": 200 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "midjourney", "settings": { "version": "7", "prompt": "This man as an astronaut walking on the Moon, cinematic light", "aspect_ratio": "2:3", "omni_ref_image": [ "https://example.com/person.jpg" ], "ow": 200 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Midjourney 7 > Moves a person, a character or an object from a photo with Omni Reference, with the similarity strength ow. Such a run costs more than a regular one. In versions 8.2 and 8.1 the edit_images field does the transfer at the price of a regular image. Value of the version field: `7` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Plain text only: Midjourney parameters (--ar, --v and others), links and options in curly braces are not accepted, there are fields for the settings and pictures. Versions 8.2 and 8.1 shorten a description longer than about 1000 characters before generating, version 7 takes the whole text. - Type: String - Minimum characters: 1 - Maximum characters: 6000 #### `aspect_ratio` (Optional) Aspect ratio: width and height as whole numbers with a colon, digits only and no spaces, for example 1:1, 16:9, 9:16, 4:5, 2:3, 21:9. - Type: String - Maximum characters: 11 - Default: `"1:1"` #### `speed` (Optional) Speed. Relaxed is cheaper but waits in a queue, Fast is quicker and costs more. The price depends on it. - Type: String - Allowed values: `relaxed`, `fast` - Default: `"relaxed"` #### `stylization` (Optional) How artistic: 0 sticks to the description, 1000 adds the most beauty but drifts from the description. Not set: 100. - Type: Integer - Minimum: 0 - Maximum: 1000 #### `chaos` (Optional) How different the four pictures are: 0 similar, 100 the most different. - Type: Integer - Minimum: 0 - Maximum: 100 #### `weirdness` (Optional) Weirdness: 0 an ordinary picture, 3000 surrealism and abstraction. - Type: Integer - Minimum: 0 - Maximum: 3000 #### `raw_mode` (Optional) Without Midjourney artistic processing: the result is closer to an ordinary photo. - Type: Boolean - Default: `false` #### `tile` (Optional) A seamless pattern that repeats in every direction: wallpapers, fabrics, backgrounds. - Type: Boolean - Default: `false` #### `seed` (Optional) The starting number. The same number and description give a similar result. Not set: random. - Type: Integer - Minimum: 0 - Maximum: 4294967295 #### `exclusions` (Optional) What must not be in the picture, words separated by commas, for example: text, people, blur. - Type: String - Maximum characters: 500 #### `image_prompts` (Optional) Image prompts: Midjourney takes the subject, composition and colors from them. Up to 4 URLs. - Type: List (String, uri) - Maximum items: 4 #### `iw` (Optional) Strength of the image prompts: 0 barely matter, 3 the strongest. Not set: 1. Works only together with image prompts. - Type: Number - Minimum: 0 - Maximum: 3 #### `style_ref_images` (Optional) Style samples: the manner, colors and mood carry over, but not the objects. Up to 3 URLs. - Type: List (String, uri) - Maximum items: 3 #### `sref_code` (Optional) A Midjourney style code, digits only, for example 123456789. Can go together with style samples. - Type: String #### `sw` (Optional) Style strength: 0 barely matters, 1000 the strongest. Not set: 100. Works only together with style samples or a style code. - Type: Integer - Minimum: 0 - Maximum: 1000 #### `enable_translation` (Optional) Translate the description into English before generating. If the translation fails or contains parameters, links or options in braces, the original description goes instead. - Type: Boolean - Default: `false` #### `omni_ref_image` (Optional) One URL of a photo of a person, a character or an object that will appear in the new picture. A run with it costs more. - Type: List (String, uri) - Maximum items: 1 #### `ow` (Optional) How closely to follow this photo: 1 a light hint, 1000 as close as possible. Not set: 100. Above 400 the result may get unpredictable. Works only together with the photo. - Type: Integer - Minimum: 1 - Maximum: 1000 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `plain_text` = `true`, `rework_button` = `false` ### Input - Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, a picture for the mask edit must be a PNG. A link must open without signing in and without redirects. - The description and exclusions are plain text only: no Midjourney parameters, links or options in curly braces. Settings and pictures are set with fields. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_prompts` | Images | jpeg, jpg, png, webp | 4 | 10 MB | | `style_ref_images` | Images | jpeg, jpg, png, webp | 3 | 10 MB | | `omni_ref_image` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A person from a photo in a new scene ```json { "model": "midjourney", "settings": { "version": "7", "prompt": "This man as an astronaut walking on the Moon, cinematic light", "aspect_ratio": "2:3", "omni_ref_image": [ "https://example.com/person.jpg" ], "ow": 200 } } ``` An image in the style of a sample ```json { "model": "midjourney", "settings": { "version": "7", "prompt": "A lighthouse on a cliff at dusk, waves crashing below", "aspect_ratio": "16:9", "style_ref_images": [ "https://example.com/style-sample.jpg" ], "sw": 300 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Four JPEG pictures per run, each as a separate file. - With Fast the result usually comes in about a minute, Relaxed waits in a queue longer. - Upscaling and variations of finished pictures are only available in the bot. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | jpg | 4 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" }, { "index": 2, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/2" }, { "index": 3, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/3" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Midjourney 7: features and prices](https://api.cyhub.ai/models/midjourney-7) - Other versions: [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Midjourney Editor API](https://api.cyhub.ai/en/models/midjourney-editor/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Veo 3.1 API > Veo 3.1 video with sound: from a prompt, from frames or from references, three quality tiers. Developer: Google Model key in the API: `veo` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "veo", "settings": { "mode": "text_to_video", "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "veo", "settings": { "mode": "text_to_video", "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "veo", "settings": { "mode": "text_to_video", "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "veo", "settings": { "mode": "text_to_video", "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a prompt > Video from text alone, no pictures are sent. Value of the mode field: `text_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Lines and sounds can be described in words. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `tier` (Optional) Quality tier; the price depends on it. - Type: String - Allowed values: `lite`, `fast`, `quality` - Default: `"lite"` #### `aspect_ratio` (Optional) Landscape 16:9 or portrait 9:16. - Type: String - Allowed values: `16:9`, `9:16` - Default: `"9:16"` #### `resolution` (Optional) Resolution of the finished video. The price depends on it. - Type: String - Allowed values: `720p`, `1080p`, `4k` - Default: `"720p"` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - A clip is always 8 seconds long. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a prompt ```json { "model": "veo", "settings": { "mode": "text_to_video", "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video with sound. - Generation takes several minutes, 4K longer. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The first frame, or the first and the last one: the model animates them by the prompt. Value of the mode field: `frames_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Lines and sounds can be described in words. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `tier` (Optional) Quality tier; the price depends on it. - Type: String - Allowed values: `lite`, `fast`, `quality` - Default: `"lite"` #### `aspect_ratio` (Optional) Landscape 16:9 or portrait 9:16. - Type: String - Allowed values: `16:9`, `9:16` - Default: `"9:16"` #### `resolution` (Optional) Resolution of the finished video. The price depends on it. - Type: String - Allowed values: `720p`, `1080p`, `4k` - Default: `"720p"` #### `image_urls` (Required) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - A clip is always 8 seconds long. - Images are URLs of JPEG, PNG or WebP files, up to 10 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 2 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "veo", "settings": { "mode": "frames_to_video", "prompt": "Камера медленно наезжает, листья шевелятся на ветру", "tier": "lite", "aspect_ratio": "16:9", "resolution": "720p", "image_urls": [ "https://example.com/first-frame.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video with sound. - Generation takes several minutes, 4K longer. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Characters and objects from your pictures in a new video. The Quality tier is not available here. Value of the mode field: `references_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Lines and sounds can be described in words. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `tier` (Optional) Quality tier; the price depends on it. Quality does not work with references. - Type: String - Allowed values: `lite`, `fast` - Default: `"lite"` #### `aspect_ratio` (Optional) Landscape 16:9 or portrait 9:16. - Type: String - Allowed values: `16:9`, `9:16` - Default: `"9:16"` #### `resolution` (Optional) Resolution of the finished video. The price depends on it. - Type: String - Allowed values: `720p`, `1080p`, `4k` - Default: `"720p"` #### `image_urls` (Required) One to three URLs of pictures with the characters or objects. - Type: List (String, uri) - Maximum items: 3 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - A clip is always 8 seconds long. - Images are URLs of JPEG, PNG or WebP files, up to 10 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 3 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A character from a picture ```json { "model": "veo", "settings": { "mode": "references_to_video", "prompt": "Этот персонаж идёт по ночному городу под дождём", "tier": "fast", "aspect_ratio": "9:16", "resolution": "1080p", "image_urls": [ "https://example.com/character.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video with sound. - Generation takes several minutes, 4K longer. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Veo 3.1: features and prices](https://api.cyhub.ai/models/veo-3-1) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Wan 3.0 API > Wan 3.0 video from the first and last frames, from references and in the Omni mode, where pictures, video and sound go together. 2 to 30 seconds, up to 1080p. Developer: Alibaba Model key in the API: `wan` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "wan", "settings": { "mode": "frames", "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают", "image_urls": [ "https://example.com/first-frame.jpg" ], "quality": "720p", "duration": "5s", "model": "3_0" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "wan", "settings": { "mode": "frames", "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают", "image_urls": [ "https://example.com/first-frame.jpg", ], "quality": "720p", "duration": "5s", "model": "3_0", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "wan", "settings": { "mode": "frames", "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают", "image_urls": [ "https://example.com/first-frame.jpg" ], "quality": "720p", "duration": "5s", "model": "3_0" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "wan", "settings": { "mode": "frames", "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают", "image_urls": [ "https://example.com/first-frame.jpg" ], "quality": "720p", "duration": "5s", "model": "3_0" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From frames > The first frame, or the first and the last one: the model animates them by the prompt. Wan 3.0 needs a frame, the other versions also work without one. Value of the mode field: `frames` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: scene, motion, camera, style. Up to 5,000 characters, up to 20,000 for Wan 3.0. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `image_urls` (Optional) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 #### `model` (Optional) Wan version. 3.0, the newest one, has no own sound and no splitting into scenes. - Type: String - Allowed values: `3_0` (Wan 3.0) - Default: `"3_0"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. Wan 2.5 at 480p offers only 16:9, 9:16 and 1:1. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Default: `"16:9"` #### `duration` (Optional) Video length: 5 or 10 seconds for Wan 2.5, 2 to 15 for 2.6 and 2.7, 2 to 30 for 3.0. The price is per second. - Type: String - Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec), `16s` (16 sec), `17s` (17 sec), `18s` (18 sec), `19s` (19 sec), `20s` (20 sec), `21s` (21 sec), `22s` (22 sec), `23s` (23 sec), `24s` (24 sec), `25s` (25 sec), `26s` (26 sec), `27s` (27 sec), `28s` (28 sec), `29s` (29 sec), `30s` (30 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.6 and 2.7 only. - Type: Boolean - Default: `false` #### `audio` (Optional) Your own sound for the video, such as a voice or music: one URL. Available in Wan 2.6 and 2.7. Sound longer than the video is cut to its length. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Frames are URLs of JPEG, PNG or WebP files up to 10 MB each. - Sound is a URL of an MP3 or WAV file up to 10 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 2 | 10 MB | | `audio` | Audio | mp3, wav | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "wan", "settings": { "mode": "frames", "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают", "image_urls": [ "https://example.com/first-frame.jpg" ], "quality": "720p", "duration": "5s" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Characters, objects and places from your pictures and videos in a new video. Versions 2.7 and 3.0. Value of the mode field: `reference` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Refer to the attachments by the labels @Image1, @Video1, each one must be mentioned. Up to 5,000 characters, up to 20,000 for Wan 3.0. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `ref_image_urls` (Optional) Pictures with characters, objects or a place, @Image1, @Image2 in the prompt in the order of the URLs. Up to 5 pictures and videos together, at least one of them is required. - Type: List (String, uri) - Maximum items: 5 #### `ref_video_urls` (Optional) Videos with a character, @Video1, @Video2 in the prompt. Each is 1 to 5 seconds, their seconds are included in the price. With a video, Wan 2.7 makes a video of 10 seconds at most. - Type: List (String, uri) - Maximum items: 5 #### `first_frame_url` (Optional) The first frame of the video, optional. With it the video takes the shape of the frame, and aspect_ratio has no effect. - Type: List (String, uri) - Maximum items: 1 #### `model` (Optional) Wan version: 2.7 or 3.0. - Type: String - Allowed values: `3_0` (Wan 3.0) - Default: `"3_0"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Default: `"16:9"` #### `duration` (Optional) Video length: 2 to 15 seconds for Wan 2.7, up to 10 with a video among the attachments; 2 to 30 for 3.0. The price is per second. - Type: String - Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec), `16s` (16 sec), `17s` (17 sec), `18s` (18 sec), `19s` (19 sec), `20s` (20 sec), `21s` (21 sec), `22s` (22 sec), `23s` (23 sec), `24s` (24 sec), `25s` (25 sec), `26s` (26 sec), `27s` (27 sec), `28s` (28 sec), `29s` (29 sec), `30s` (30 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.7 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Every attachment must be mentioned in the prompt by its label: @Image1, @Image2, @Video1 and so on. The number is the position of the URL in the field of its type. Write it exactly like this: capital letter, no space. - Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, videos are URLs of MP4 or MOV files up to 100 MB. - A video goes to the model whole, without trimming, and its seconds are included in the price. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `ref_image_urls` | Images | jpeg, jpg, png, webp | 5 | 10 MB | | `ref_video_urls` | Video | mp4, mov | 5 | 100 MB | | `first_frame_url` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A character from a picture ```json { "model": "wan", "settings": { "mode": "reference", "prompt": "@Image1 идёт по ночному городу под дождём, камера следует за ним", "ref_image_urls": [ "https://example.com/hero.png" ], "aspect_ratio": "9:16", "duration": "5s" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Omni > Pictures, video and sound together, each attachment with its own label in the prompt. Wan 3.0 only. Value of the mode field: `omni` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Refer to the attachments by the labels @Image1, @Video1, @Audio1, each one must be mentioned. Up to 20,000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `ref_image_urls` (Optional) Pictures, @Image1, @Image2 in the prompt in the order of the URLs, up to 10. - Type: List (String, uri) - Maximum items: 10 #### `ref_video_urls` (Optional) Videos, @Video1, @Video2 in the prompt. Each is 1 to 15 seconds, 15 at most together. Their seconds are included in the price. - Type: List (String, uri) - Maximum items: 5 #### `ref_audio_urls` (Optional) Sound, such as a voice for a line, @Audio1, @Audio2 in the prompt. Each is 1 to 15 seconds, 15 at most together. - Type: List (String, uri) - Maximum items: 5 #### `model` (Optional) Wan version: only 3.0 has this mode. - Type: String - Allowed values: `3_0` (Wan 3.0) - Default: `"3_0"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Default: `"16:9"` #### `duration` (Optional) Video length from 2 to 30 seconds. The price is per second. - Type: String - Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec), `16s` (16 sec), `17s` (17 sec), `18s` (18 sec), `19s` (19 sec), `20s` (20 sec), `21s` (21 sec), `22s` (22 sec), `23s` (23 sec), `24s` (24 sec), `25s` (25 sec), `26s` (26 sec), `27s` (27 sec), `28s` (28 sec), `29s` (29 sec), `30s` (30 sec) - Default: `"5s"` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Every attachment must be mentioned in the prompt by its label: @Image1, @Image2, @Video1 and so on. The number is the position of the URL in the field of its type. Write it exactly like this: capital letter, no space. - At least one attachment is needed. - Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, videos are URLs of MP4 or MOV files up to 100 MB, sound is URLs of MP3 or WAV files up to 10 MB. - A video goes to the model whole, without trimming, and its seconds are included in the price. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `ref_image_urls` | Images | jpeg, jpg, png, webp | 10 | 10 MB | | `ref_video_urls` | Video | mp4, mov | 5 | 100 MB | | `ref_audio_urls` | Audio | mp3, wav | 5 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Two characters talking ```json { "model": "wan", "settings": { "mode": "omni", "prompt": "@Image1 приходит к @Image2 и говорит ему @Audio1. Фон как в @Video1, звук из видео не брать", "ref_image_urls": [ "https://example.com/fox.png", "https://example.com/bear.png" ], "ref_video_urls": [ "https://example.com/forest.mp4" ], "ref_audio_urls": [ "https://example.com/line.mp3" ], "quality": "480p", "duration": "5s" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Wan 3.0: features and prices](https://api.cyhub.ai/models/wan-3) - Other versions: [Wan 2.7 API](https://api.cyhub.ai/en/models/wan-2-7/api.md), [Wan 2.6 API](https://api.cyhub.ai/en/models/wan-2-6/api.md), [Wan 2.5 API](https://api.cyhub.ai/en/models/wan-2-5/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Wan 2.7 API > Wan 2.7 video from a prompt, from the first and last frames or from references with characters, objects and places. 2 to 15 seconds, 720p or 1080p, with the option to add your own sound and split the video into scenes. Developer: Alibaba Model key in the API: `wan` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "wan", "settings": { "mode": "text", "model": "2_7", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "wan", "settings": { "mode": "text", "model": "2_7", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "wan", "settings": { "mode": "text", "model": "2_7", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "wan", "settings": { "mode": "text", "model": "2_7", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a prompt > Video from text alone. Versions 2.5, 2.6 and 2.7; Wan 3.0 has no such mode. Value of the mode field: `text` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: scene, motion, camera, style. Up to 5,000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `model` (Optional) Wan version: 2.5, 2.6 or 2.7. - Type: String - Allowed values: `2_7` (Wan 2.7) - Default: `"2_7"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. Wan 2.5 at 480p offers only 16:9, 9:16 and 1:1. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Default: `"16:9"` #### `duration` (Optional) Video length: 5 or 10 seconds for Wan 2.5, 2 to 15 for 2.6 and 2.7. The price is per second. - Type: String - Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.6 and 2.7 only. - Type: Boolean - Default: `false` #### `audio` (Optional) Your own sound for the video, such as a voice or music: one URL. Available in Wan 2.6 and 2.7. Sound longer than the video is cut to its length. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Sound is a URL of an MP3 or WAV file up to 10 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a prompt ```json { "model": "wan", "settings": { "mode": "text", "model": "2_7", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The first frame, or the first and the last one: the model animates them by the prompt. Wan 3.0 needs a frame, the other versions also work without one. Value of the mode field: `frames` This page is about Wan 2.7: send model = 2_7. Without the model field the task runs on 3_0. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: scene, motion, camera, style. Up to 5,000 characters, up to 20,000 for Wan 3.0. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `image_urls` (Optional) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 #### `model` (Optional) Wan version. 3.0, the newest one, has no own sound and no splitting into scenes. - Type: String - Allowed values: `2_7` (Wan 2.7) - Default: `"3_0"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. Wan 2.5 at 480p offers only 16:9, 9:16 and 1:1. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Default: `"16:9"` #### `duration` (Optional) Video length: 5 or 10 seconds for Wan 2.5, 2 to 15 for 2.6 and 2.7, 2 to 30 for 3.0. The price is per second. - Type: String - Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.6 and 2.7 only. - Type: Boolean - Default: `false` #### `audio` (Optional) Your own sound for the video, such as a voice or music: one URL. Available in Wan 2.6 and 2.7. Sound longer than the video is cut to its length. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Frames are URLs of JPEG, PNG or WebP files up to 10 MB each. - Sound is a URL of an MP3 or WAV file up to 10 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 2 | 10 MB | | `audio` | Audio | mp3, wav | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A frame that speaks in your voice ```json { "model": "wan", "settings": { "mode": "frames", "model": "2_7", "prompt": "Лев смотрит в камеру и говорит этим голосом", "image_urls": [ "https://example.com/lion.jpg" ], "audio": [ "https://example.com/voice.mp3" ], "duration": "5s" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Characters, objects and places from your pictures and videos in a new video. Versions 2.7 and 3.0. Value of the mode field: `reference` This page is about Wan 2.7: send model = 2_7. Without the model field the task runs on 3_0. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Refer to the attachments by the labels @Image1, @Video1, each one must be mentioned. Up to 5,000 characters, up to 20,000 for Wan 3.0. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `ref_image_urls` (Optional) Pictures with characters, objects or a place, @Image1, @Image2 in the prompt in the order of the URLs. Up to 5 pictures and videos together, at least one of them is required. - Type: List (String, uri) - Maximum items: 5 #### `ref_video_urls` (Optional) Videos with a character, @Video1, @Video2 in the prompt. Each is 1 to 5 seconds, their seconds are included in the price. With a video, Wan 2.7 makes a video of 10 seconds at most. - Type: List (String, uri) - Maximum items: 5 #### `first_frame_url` (Optional) The first frame of the video, optional. With it the video takes the shape of the frame, and aspect_ratio has no effect. - Type: List (String, uri) - Maximum items: 1 #### `model` (Optional) Wan version: 2.7 or 3.0. - Type: String - Allowed values: `2_7` (Wan 2.7) - Default: `"3_0"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Default: `"16:9"` #### `duration` (Optional) Video length: 2 to 15 seconds for Wan 2.7, up to 10 with a video among the attachments; 2 to 30 for 3.0. The price is per second. - Type: String - Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.7 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Every attachment must be mentioned in the prompt by its label: @Image1, @Image2, @Video1 and so on. The number is the position of the URL in the field of its type. Write it exactly like this: capital letter, no space. - Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, videos are URLs of MP4 or MOV files up to 100 MB. - A video goes to the model whole, without trimming, and its seconds are included in the price. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `ref_image_urls` | Images | jpeg, jpg, png, webp | 5 | 10 MB | | `ref_video_urls` | Video | mp4, mov | 5 | 100 MB | | `first_frame_url` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Two characters and a first frame ```json { "model": "wan", "settings": { "mode": "reference", "model": "2_7", "prompt": "@Image1 встречает @Video1 у входа в кафе и машет рукой", "ref_image_urls": [ "https://example.com/hero.png" ], "ref_video_urls": [ "https://example.com/friend.mp4" ], "first_frame_url": [ "https://example.com/cafe.jpg" ], "duration": "5s" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Wan 2.7: features and prices](https://api.cyhub.ai/models/wan-2-7) - Other versions: [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [Wan 2.6 API](https://api.cyhub.ai/en/models/wan-2-6/api.md), [Wan 2.5 API](https://api.cyhub.ai/en/models/wan-2-5/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Wan 2.6 API > Wan 2.6 video from a prompt or from the first and last frames. 2 to 15 seconds, 720p or 1080p, with the option to add your own sound and split the video into scenes. Developer: Alibaba Model key in the API: `wan` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "wan", "settings": { "mode": "text", "model": "2_6", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "wan", "settings": { "mode": "text", "model": "2_6", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "wan", "settings": { "mode": "text", "model": "2_6", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "wan", "settings": { "mode": "text", "model": "2_6", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a prompt > Video from text alone. Versions 2.5, 2.6 and 2.7; Wan 3.0 has no such mode. Value of the mode field: `text` This page is about Wan 2.6: send model = 2_6. Without the model field the task runs on 2_7. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: scene, motion, camera, style. Up to 5,000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `model` (Optional) Wan version: 2.5, 2.6 or 2.7. - Type: String - Allowed values: `2_6` (Wan 2.6) - Default: `"2_7"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. Wan 2.5 at 480p offers only 16:9, 9:16 and 1:1. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Default: `"16:9"` #### `duration` (Optional) Video length: 5 or 10 seconds for Wan 2.5, 2 to 15 for 2.6 and 2.7. The price is per second. - Type: String - Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.6 and 2.7 only. - Type: Boolean - Default: `false` #### `audio` (Optional) Your own sound for the video, such as a voice or music: one URL. Available in Wan 2.6 and 2.7. Sound longer than the video is cut to its length. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Sound is a URL of an MP3 or WAV file up to 10 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a prompt ```json { "model": "wan", "settings": { "mode": "text", "model": "2_6", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The first frame, or the first and the last one: the model animates them by the prompt. Wan 3.0 needs a frame, the other versions also work without one. Value of the mode field: `frames` This page is about Wan 2.6: send model = 2_6. Without the model field the task runs on 3_0. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: scene, motion, camera, style. Up to 5,000 characters, up to 20,000 for Wan 3.0. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `image_urls` (Optional) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 #### `model` (Optional) Wan version. 3.0, the newest one, has no own sound and no splitting into scenes. - Type: String - Allowed values: `2_6` (Wan 2.6) - Default: `"3_0"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. Wan 2.5 at 480p offers only 16:9, 9:16 and 1:1. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Default: `"16:9"` #### `duration` (Optional) Video length: 5 or 10 seconds for Wan 2.5, 2 to 15 for 2.6 and 2.7, 2 to 30 for 3.0. The price is per second. - Type: String - Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.6 and 2.7 only. - Type: Boolean - Default: `false` #### `audio` (Optional) Your own sound for the video, such as a voice or music: one URL. Available in Wan 2.6 and 2.7. Sound longer than the video is cut to its length. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Frames are URLs of JPEG, PNG or WebP files up to 10 MB each. - Sound is a URL of an MP3 or WAV file up to 10 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 2 | 10 MB | | `audio` | Audio | mp3, wav | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "wan", "settings": { "mode": "frames", "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают", "image_urls": [ "https://example.com/first-frame.jpg" ], "quality": "720p", "duration": "5s", "model": "2_6" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Wan 2.6: features and prices](https://api.cyhub.ai/models/wan-2-6) - Other versions: [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [Wan 2.7 API](https://api.cyhub.ai/en/models/wan-2-7/api.md), [Wan 2.5 API](https://api.cyhub.ai/en/models/wan-2-5/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Wan 2.5 API > Wan 2.5 video from a prompt or from the first and last frames: 5 or 10 seconds, 480p to 1080p. Developer: Alibaba Model key in the API: `wan` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "wan", "settings": { "mode": "text", "model": "2_5", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "wan", "settings": { "mode": "text", "model": "2_5", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "wan", "settings": { "mode": "text", "model": "2_5", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "wan", "settings": { "mode": "text", "model": "2_5", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a prompt > Video from text alone. Versions 2.5, 2.6 and 2.7; Wan 3.0 has no such mode. Value of the mode field: `text` This page is about Wan 2.5: send model = 2_5. Without the model field the task runs on 2_7. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: scene, motion, camera, style. Up to 5,000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `model` (Optional) Wan version: 2.5, 2.6 or 2.7. - Type: String - Allowed values: `2_5` (Wan 2.5) - Default: `"2_7"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. Wan 2.5 at 480p offers only 16:9, 9:16 and 1:1. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Exceptions: | `quality` | `aspect_ratio` | |---|---| | `480p` | except `4:3`, `3:4` | - Default: `"16:9"` #### `duration` (Optional) Video length: 5 or 10 seconds for Wan 2.5, 2 to 15 for 2.6 and 2.7. The price is per second. - Type: String - Allowed values: `5s` (5 sec), `10s` (10 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.6 and 2.7 only. - Type: Boolean - Default: `false` #### `audio` (Optional) Your own sound for the video, such as a voice or music: one URL. Available in Wan 2.6 and 2.7. Sound longer than the video is cut to its length. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Sound is a URL of an MP3 or WAV file up to 10 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio` | Audio | mp3, wav | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a prompt ```json { "model": "wan", "settings": { "mode": "text", "model": "2_5", "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается", "quality": "720p", "aspect_ratio": "16:9", "duration": "5s" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The first frame, or the first and the last one: the model animates them by the prompt. Wan 3.0 needs a frame, the other versions also work without one. Value of the mode field: `frames` This page is about Wan 2.5: send model = 2_5. Without the model field the task runs on 3_0. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: scene, motion, camera, style. Up to 5,000 characters, up to 20,000 for Wan 3.0. - Type: String - Minimum characters: 1 - Maximum characters: 20000 #### `image_urls` (Optional) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 #### `model` (Optional) Wan version. 3.0, the newest one, has no own sound and no splitting into scenes. - Type: String - Allowed values: `2_5` (Wan 2.5) - Default: `"3_0"` #### `quality` (Optional) Video resolution; the set depends on the version. The price per second depends on it. - Type: String - Allowed values: `480p`, `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape. Wan 2.5 at 480p offers only 16:9, 9:16 and 1:1. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - The set depends on `quality`. - Exceptions: | `quality` | `aspect_ratio` | |---|---| | `480p` | except `4:3`, `3:4` | - Default: `"16:9"` #### `duration` (Optional) Video length: 5 or 10 seconds for Wan 2.5, 2 to 15 for 2.6 and 2.7, 2 to 30 for 3.0. The price is per second. - Type: String - Allowed values: `5s` (5 sec), `10s` (10 sec) - Default: `"5s"` #### `multi_shots` (Optional) Split the video into several scenes. Wan 2.6 and 2.7 only. - Type: Boolean - Default: `false` #### `audio` (Optional) Your own sound for the video, such as a voice or music: one URL. Available in Wan 2.6 and 2.7. Sound longer than the video is cut to its length. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Frames are URLs of JPEG, PNG or WebP files up to 10 MB each. - Sound is a URL of an MP3 or WAV file up to 10 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 2 | 10 MB | | `audio` | Audio | mp3, wav | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "wan", "settings": { "mode": "frames", "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают", "image_urls": [ "https://example.com/first-frame.jpg" ], "quality": "720p", "duration": "5s", "model": "2_5" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 5 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Wan 2.5: features and prices](https://api.cyhub.ai/models/wan-2-5) - Other versions: [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [Wan 2.7 API](https://api.cyhub.ai/en/models/wan-2-7/api.md), [Wan 2.6 API](https://api.cyhub.ai/en/models/wan-2-6/api.md) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # MiniMax H3 (Hailuo 03) API > MiniMax H3 (Hailuo 03) video with sound, up to 15 seconds: from a prompt, from the first and last frames or from references. References can be pictures, videos and audio. Quality 768P or 2K, the model makes the sound itself. Developer: MiniMax Model key in the API: `minimax_h3` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "minimax_h3", "settings": { "mode": "text_to_video", "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег", "resolution": "768P", "aspect_ratio": "16:9", "duration": 6 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "minimax_h3", "settings": { "mode": "text_to_video", "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег", "resolution": "768P", "aspect_ratio": "16:9", "duration": 6, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "minimax_h3", "settings": { "mode": "text_to_video", "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег", "resolution": "768P", "aspect_ratio": "16:9", "duration": 6 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "minimax_h3", "settings": { "mode": "text_to_video", "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег", "resolution": "768P", "aspect_ratio": "16:9", "duration": 6 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a prompt > Video from text alone, no files are sent. Value of the mode field: `text_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video, how the camera moves, what it sounds like. A timed script works too: what happens from 0 to 3 seconds, from 3 to 7, and so on. - Type: String - Minimum characters: 1 - Maximum characters: 7000 #### `resolution` (Optional) Video quality. 2K is more detailed, a second costs more. - Type: String - Allowed values: `768P`, `2K` - Default: `"768P"` #### `duration` (Optional) Video length in seconds, 4 to 15. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 15 - Default: `6` #### `aspect_ratio` (Optional) Frame shape: from cinematic 21:9 to portrait 9:16. - Type: String - Allowed values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` - Default: `"16:9"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a prompt ```json { "model": "minimax_h3", "settings": { "mode": "text_to_video", "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег", "resolution": "768P", "aspect_ratio": "16:9", "duration": 6 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video with sound: the model makes the sound itself. - Generation usually takes 1 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > The video starts with the first frame. If the last frame is given too, the video ends with it. The video takes the shape of the frames. Value of the mode field: `image_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video, how the camera moves, what it sounds like. A timed script works too: what happens from 0 to 3 seconds, from 3 to 7, and so on. - Type: String - Minimum characters: 1 - Maximum characters: 7000 #### `resolution` (Optional) Video quality. 2K is more detailed, a second costs more. - Type: String - Allowed values: `768P`, `2K` - Default: `"768P"` #### `duration` (Optional) Video length in seconds, 4 to 15. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 15 - Default: `6` #### `image_urls` (Required) One URL: the first frame. Two URLs: the first and the last frames. - Type: List (String, uri) - Maximum items: 2 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG or WebP files up to 30 MB each, sides from 256 to 5,760 pixels, shape from 2:5 to 5:2. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 2 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "minimax_h3", "settings": { "mode": "image_to_video", "prompt": "Героиня поворачивается и улыбается, камера медленно наезжает", "image_urls": [ "https://example.com/first-frame.jpg" ], "duration": 6 } } ``` From the first frame to the last ```json { "model": "minimax_h3", "settings": { "mode": "image_to_video", "prompt": "Бутон медленно раскрывается в цветок", "image_urls": [ "https://example.com/bud.jpg", "https://example.com/flower.jpg" ], "resolution": "2K", "duration": 5 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video with sound: the model makes the sound itself. - Generation usually takes 1 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > The model carries characters and objects from the pictures, motion and editing from the videos, voice and rhythm from the audio into a new video. At least one picture or one video is needed. Value of the mode field: `reference_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video, how the camera moves, what it sounds like. A timed script works too: what happens from 0 to 3 seconds, from 3 to 7, and so on. - Type: String - Minimum characters: 1 - Maximum characters: 7000 #### `resolution` (Optional) Video quality. 2K is more detailed, a second costs more. - Type: String - Allowed values: `768P`, `2K` - Default: `"768P"` #### `duration` (Optional) Video length in seconds, 4 to 15. The price is per second. - Type: Integer - Minimum: 4 - Maximum: 15 - Default: `6` #### `aspect_ratio` (Optional) Frame shape. adaptive: the model picks it from the attached files. - Type: String - Allowed values: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` - Default: `"16:9"` #### `image_urls` (Optional) Up to 9 URLs of pictures with the characters, objects or style. The first 5 are free, each next one adds to the price. - Type: List (String, uri) - Maximum items: 9 #### `video_urls` (Optional) Up to 3 URLs of videos the model takes motion and editing from. Their seconds are billed like seconds of the result. - Type: List (String, uri) - Maximum items: 3 #### `audio_urls` (Optional) Up to 3 URLs of audio: a voice or music the model matches speech and rhythm to. Free, only together with a picture or a video. - Type: List (String, uri) - Maximum items: 3 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG or WebP files up to 30 MB each, sides from 256 to 5,760 pixels, shape from 2:5 to 5:2. - Videos are URLs of MP4 or MOV files (H.264 or H.265) up to 50 MB each: each 2 to 15 seconds long, no more than 15 seconds all together, sides from 256 to 5,760 pixels, shape from 2:5 to 5:2, 23.976 to 60 frames per second. - Audio files are URLs of MP3 or WAV files up to 15 MB each: each 2 to 15 seconds long, no more than 15 seconds all together. - Videos and audio go to the model whole. The video price follows the length of the files themselves: their seconds are added to the seconds of the result. - Video and audio lengths are checked before anything goes to the model: if they do not fit, the task ends with a refusal that names the reason and costs nothing. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 9 | 30 MB | | `video_urls` | Video | mp4, mov | 3 | 50 MB | | `audio_urls` | Audio | mp3, wav | 3 | 15 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A character from a picture ```json { "model": "minimax_h3", "settings": { "mode": "reference_to_video", "prompt": "Девушка с картинки идёт по ночному городу под дождём", "image_urls": [ "https://example.com/girl.png" ], "aspect_ratio": "9:16", "duration": 6 } } ``` Motion from a video, music from audio ```json { "model": "minimax_h3", "settings": { "mode": "reference_to_video", "prompt": "Девушка с картинки танцует как в видео под музыку из аудио", "image_urls": [ "https://example.com/girl.png" ], "video_urls": [ "https://example.com/dance.mp4" ], "audio_urls": [ "https://example.com/music.mp3" ], "aspect_ratio": "adaptive", "duration": 8 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video with sound: the model makes the sound itself. - Generation usually takes 1 to 10 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [MiniMax H3 (Hailuo 03): features and prices](https://api.cyhub.ai/models/minimax-h3) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Gemini Omni API > Gemini Omni video from a prompt: with pictures, a source video and a voice, or from the first frame to the last one. Developer: Google Model key in the API: `gemeni_omni` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "gemeni_omni", "settings": { "mode": "materials", "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом", "duration": "6", "aspect_ratio": "9:16", "resolution": "720p", "voice": "achernar" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "gemeni_omni", "settings": { "mode": "materials", "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом", "duration": "6", "aspect_ratio": "9:16", "resolution": "720p", "voice": "achernar", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "gemeni_omni", "settings": { "mode": "materials", "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом", "duration": "6", "aspect_ratio": "9:16", "resolution": "720p", "voice": "achernar" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "gemeni_omni", "settings": { "mode": "materials", "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом", "duration": "6", "aspect_ratio": "9:16", "resolution": "720p", "voice": "achernar" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a prompt and materials > Video from a prompt. You can attach pictures and a source video and pick a voice, all of it optional. Materials take at most seven slots: a picture takes one, a video two. Value of the mode field: `materials` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: who acts, where, how the camera moves. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `duration` (Optional) Clip length in seconds; the price depends on it. - Type: String - Allowed values: `4`, `6`, `8`, `10` - Default: `"4"` #### `aspect_ratio` (Optional) Portrait 9:16 or landscape 16:9. - Type: String - Allowed values: `9:16`, `16:9` - Default: `"9:16"` #### `resolution` (Optional) Resolution of the finished video. 360p, 720p and 1080p cost the same, 4K costs more. - Type: String - Allowed values: `360p`, `720p`, `1080p`, `4k` - Default: `"720p"` #### `image_urls` (Optional) Up to seven picture URLs: people, objects, places, style. No more than five with a source video. The model sees them itself, so the prompt can simply say, for example, "the woman from the photo walks down the street". - Type: List (String, uri) - Maximum items: 7 #### `video_url` (Optional) One URL of a source video no longer than 30 seconds. The model takes its first 10 seconds. With a video, duration is ignored: the model picks the length of the new clip, and the price is the same for any length. - Type: List (String, uri) - Maximum items: 1 #### `voice` (Optional) Optional: a voice from the ready-made set that speaks in the video. The voices are English-speaking and may have an accent in other languages. - Type: String - Allowed values: `achernar`, `achird`, `algenib`, `algieba`, `alnilam`, `aoede`, `autonoe`, `callirrhoe`, `charon`, `despina`, `enceladus`, `erinome`, `fenrir`, `gacrux`, `iapetus`, `kore`, `laomedeia`, `leda`, `orus`, `puck`, `pulcherrima`, `rasalgethi`, `sadachbia`, `sadaltager`, `schedar`, `sulafat`, `umbriel`, `vindemiatrix`, `zephyr`, `zubenelgenubi` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Pictures are URLs of JPEG, PNG or WebP files, up to 20 MB each. - A video is a URL of an MP4 or MOV file up to 100 MB and no longer than 30 seconds. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 7 | 20 MB | | `video_url` | Video | mp4, mov | 1 | 100 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a prompt ```json { "model": "gemeni_omni", "settings": { "mode": "materials", "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом", "duration": "6", "aspect_ratio": "9:16", "resolution": "720p" } } ``` Video from pictures ```json { "model": "gemeni_omni", "settings": { "mode": "materials", "prompt": "Женщина с фото идёт по набережной на закате", "image_urls": [ "https://example.com/woman.jpg", "https://example.com/embankment.jpg" ], "duration": "8", "aspect_ratio": "16:9" } } ``` From a source video with a voice ```json { "model": "gemeni_omni", "settings": { "mode": "materials", "prompt": "Тот же танец на крыше под дождём, в конце танцор говорит «Поехали!»", "video_url": [ "https://example.com/dance.mp4" ], "voice": "puck" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 3 to 15 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## First and last frame > The video runs from the first frame to the last one. The first frame is required, the last one is optional. The model takes no other materials in this mode. Value of the mode field: `frames` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: who acts, where, how the camera moves. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `duration` (Optional) Clip length in seconds; the price depends on it. - Type: String - Allowed values: `4`, `6`, `8`, `10` - Default: `"4"` #### `aspect_ratio` (Optional) Portrait 9:16 or landscape 16:9. - Type: String - Allowed values: `9:16`, `16:9` - Default: `"9:16"` #### `resolution` (Optional) Resolution of the finished video. 360p, 720p and 1080p cost the same, 4K costs more. - Type: String - Allowed values: `360p`, `720p`, `1080p`, `4k` - Default: `"720p"` #### `first_frame_url` (Required) One picture URL: the first frame of the video. - Type: List (String, uri) - Maximum items: 1 #### `last_frame_url` (Optional) One picture URL: the last frame of the video. Only together with the first one. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Pictures are URLs of JPEG, PNG or WebP files, up to 20 MB each. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `first_frame_url` | Images | jpeg, jpg, png, webp | 1 | 20 MB | | `last_frame_url` | Images | jpeg, jpg, png, webp | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. From the first frame to the last one ```json { "model": "gemeni_omni", "settings": { "mode": "frames", "prompt": "Бутон медленно раскрывается в цветок, мягкий утренний свет", "first_frame_url": [ "https://example.com/bud.png" ], "last_frame_url": [ "https://example.com/flower.png" ], "duration": "4" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation usually takes 3 to 15 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Gemini Omni: features and prices](https://api.cyhub.ai/models/gemini-omni) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Grok Imagine Video API > Grok video: from a description, from a picture or from references, editing and continuing your clip. Two models: Grok with clips up to 30 seconds and Grok Pro. Developer: xAI Model key in the API: `grok_video` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "grok_video", "settings": { "mode": "text_to_video", "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом", "model": "grok", "aspect_ratio": "16:9", "duration": 10 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "grok_video", "settings": { "mode": "text_to_video", "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом", "model": "grok", "aspect_ratio": "16:9", "duration": 10, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "grok_video", "settings": { "mode": "text_to_video", "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом", "model": "grok", "aspect_ratio": "16:9", "duration": 10 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "grok_video", "settings": { "mode": "text_to_video", "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом", "model": "grok", "aspect_ratio": "16:9", "duration": 10 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A video from text alone, no files are sent. Value of the mode field: `text_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Up to 5000 characters for Grok, up to 4096 Latin characters for Grok Pro, which counts a Cyrillic letter as two. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `model` (Optional) The model. Grok is cheaper, a clip up to 30 seconds, has generation modes. Grok Pro gives higher quality, a clip up to 15 seconds. - Type: String - Allowed values: `grok`, `grok_pro` (Grok Pro) - Default: `"grok"` #### `generation_mode` (Optional) The mood of a Grok clip, see the options. Grok Pro has no moods, keep "Normal". - Type: String - Allowed values: `normal`, `fun`, `spicy` - Default: `"normal"` #### `aspect_ratio` (Optional) Aspect ratio. Grok Pro has more of them: 4:3 and 3:4 too. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `3:2`, `2:3` - The set depends on `model`. - Exceptions: | `model` | `aspect_ratio` | |---|---| | `grok_pro` | plus `4:3`, `3:4` | - Default: `"9:16"` #### `quality` (Optional) Video resolution. 720p costs more. - Type: String - Allowed values: `480p`, `720p` - Default: `"480p"` #### `duration` (Optional) Video length in seconds: 6 to 30 for Grok, 1 to 15 for Grok Pro. The price is per second. - Type: Integer - Minimum: 1 - Maximum: 30 - Default: `6` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A video from a description ```json { "model": "grok_video", "settings": { "mode": "text_to_video", "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом", "model": "grok", "aspect_ratio": "16:9", "duration": 10 } } ``` Grok Pro in 720p ```json { "model": "grok_video", "settings": { "mode": "text_to_video", "prompt": "Бармен подбрасывает шейкер и ловит его за спиной, тёплый свет бара", "model": "grok_pro", "aspect_ratio": "4:3", "quality": "720p", "duration": 8 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 2 to 5 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From a picture > The video starts from your picture, or the model takes characters and objects from reference pictures. A picture or at least one reference is needed. Value of the mode field: `image_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Up to 4096 characters, up to 5000 for Grok with references. Grok Pro counts a Cyrillic letter as two. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `model` (Optional) The model. Grok is cheaper, a clip up to 30 seconds, has generation modes. Grok Pro gives higher quality, a clip up to 15 seconds. - Type: String - Allowed values: `grok`, `grok_pro` (Grok Pro) - Default: `"grok"` #### `image_urls` (Optional) One URL of the picture the video starts from. May be left out when references are given. - Type: List (String, uri) - Maximum items: 1 #### `reference_image_urls` (Optional) Up to 7 URLs of pictures with characters, objects or a style. Grok takes no more than 7 together with the main picture, Grok Pro does not take the main picture together with references. - Type: List (String, uri) - Maximum items: 7 #### `generation_mode` (Optional) The mood of the clip: "Normal" or "Fun". Works only for Grok with references, otherwise keep "Normal". - Type: String - Allowed values: `normal`, `fun` - Default: `"normal"` #### `aspect_ratio` (Optional) Aspect ratio. Auto is only for Grok with one main picture and no references, 4:3 and 3:4 are not available for Grok with references. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `auto` - The set depends on `model`. - Exceptions: | `model` | `aspect_ratio` | |---|---| | `grok_pro` | except `auto` | - Default: `"9:16"` #### `quality` (Optional) Video resolution. 720p costs more. - Type: String - Allowed values: `480p`, `720p` - Default: `"480p"` #### `duration` (Optional) Video length in seconds: 1 to 15, 6 to 30 for Grok with references, up to 10 for Grok Pro with references. The price is per second. - Type: Integer - Minimum: 1 - Maximum: 30 - Default: `6` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each. - With one picture for Grok (the main one or a single reference), the aspect ratio comes from the picture. Grok Pro stretches the main picture to the chosen aspect ratio. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | | `reference_image_urls` | Images | jpeg, jpg, png, webp | 7 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a picture ```json { "model": "grok_video", "settings": { "mode": "image_to_video", "prompt": "Камера медленно наезжает, волосы героини развеваются на ветру", "image_urls": [ "https://example.com/first-frame.jpg" ], "duration": 8 } } ``` A character from references ```json { "model": "grok_video", "settings": { "mode": "image_to_video", "prompt": "Этот персонаж в этом пальто идёт по ночному городу под дождём", "model": "grok_pro", "duration": 8, "reference_image_urls": [ "https://example.com/character.png", "https://example.com/coat.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 2 to 5 minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video editing > Grok Pro changes your clip by the description: clothes, objects, colours. The model tries to keep the rest of the shot. Value of the mode field: `video_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to change in the clip, up to 4096 Latin characters: a Cyrillic letter counts as two. - Type: String - Minimum characters: 1 - Maximum characters: 4096 #### `video_urls` (Required) One URL of an MP4 clip no longer than 8.7 seconds. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true`, `model` = `"grok_pro"` ### Input - The clip is a URL of an MP4 file, and the URL must end in .mp4. At most 8.7 seconds long, the whole clip is sent, there is no trimming. - xAI names no size limit, 50 MB is our recommendation, not its limit. - The price is per second of the source clip, a started second counts as a whole one. It is counted as for 720p. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4 | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Put on a hat ```json { "model": "grok_video", "settings": { "mode": "video_to_video", "prompt": "Надень на героиню широкополую чёрную шляпу", "video_urls": [ "https://example.com/clip.mp4" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 2 to 5 minutes. - The length and aspect ratio of the source clip, its resolution too, but no higher than 720p. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video continuation > Grok Pro continues your clip from its last frame by a description of what happens next. Value of the mode field: `video_extend` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens next, up to 4096 Latin characters: a Cyrillic letter counts as two. - Type: String - Minimum characters: 1 - Maximum characters: 4096 #### `video_urls` (Required) One URL of an MP4 clip 2 to 15 seconds long. - Type: List (String, uri) - Maximum items: 1 #### `duration` (Optional) Length of the continuation in seconds, 2 to 10. Every second of the continuation adds to the price. - Type: Integer - Minimum: 2 - Maximum: 10 - Default: `6` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true`, `model` = `"grok_pro"` ### Input - The clip is a URL of an MP4 file, and the URL must end in .mp4. 2 to 15 seconds long, the whole clip is sent, there is no trimming. - xAI names no size limit, 50 MB is our recommendation, not its limit. - The price covers the seconds of the source clip and the seconds of the finished video, that is the source together with the continuation. A started second counts as a whole one, the price is as for 720p. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4 | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Continue a clip ```json { "model": "grok_video", "settings": { "mode": "video_extend", "prompt": "Камера отъезжает и показывает весь город с высоты", "video_urls": [ "https://example.com/clip.mp4" ], "duration": 6 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 2 to 5 minutes. - The finished video is the source clip together with the continuation. The aspect ratio and resolution of the source, but no higher than 720p. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Grok Imagine Video: features and prices](https://api.cyhub.ai/models/grok-video) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Grok Imagine 2.0 API > Grok Imagine 2.0 images by xAI from a text description, five aspect ratios. Developer: xAI Model key in the API: `grok_image2` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "grok_image2", "settings": { "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы", "aspect_ratio": "3:2" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "grok_image2", "settings": { "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы", "aspect_ratio": "3:2", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "grok_image2", "settings": { "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы", "aspect_ratio": "3:2" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "grok_image2", "settings": { "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы", "aspect_ratio": "3:2" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Parameters Model parameters go inside settings. Omitted optional fields take their default values. ### `prompt` (Required) What to draw: who is in frame, what is around, how it is shot, the light and the mood. - Type: String - Minimum characters: 1 - Maximum characters: 5000 ### `aspect_ratio` (Optional) Aspect ratio: 1:1 square, 2:3 and 3:2 like a photograph, 16:9 wide frame, 9:16 vertical. - Type: String - Allowed values: `1:1`, `2:3`, `3:2`, `16:9`, `9:16` - Default: `"1:1"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `edit_button` = `false` ## Input - Text only: the model does not take pictures as input. ## Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. An image from a description ```json { "model": "grok_image2", "settings": { "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы", "aspect_ratio": "3:2" } } ``` A vertical image for Stories ```json { "model": "grok_image2", "settings": { "prompt": "Девушка в жёлтом дождевике на мокрой улице ночного Токио, неоновые вывески", "aspect_ratio": "9:16" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ## Output - One image per run, usually in 1-4 minutes. - Reworking a finished picture piece by piece is only available in the bot. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | jpg, png | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Grok Imagine 2.0: features and prices](https://api.cyhub.ai/models/grok-imagine-2) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # FLUX 3 API > FLUX 3 video with sound up to 20 seconds: from a description, from frames or continuing an existing clip. A draft costs about a third of a full video. Developer: Black Forest Labs Model key in the API: `flux3` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "flux3", "settings": { "mode": "t2v", "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки", "aspect_ratio": "16:9", "duration": 8 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "flux3", "settings": { "mode": "t2v", "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки", "aspect_ratio": "16:9", "duration": 8, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "flux3", "settings": { "mode": "t2v", "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки", "aspect_ratio": "16:9", "duration": 8 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "flux3", "settings": { "mode": "t2v", "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки", "aspect_ratio": "16:9", "duration": 8 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A video from text alone, no files are sent. Value of the mode field: `t2v` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the scene, the camera movement, the sounds. Spoken lines and on-screen text can be described too. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `render` (Optional) A full video or a draft. A draft is faster, always HD and costs about a third of a full video. A draft cannot be rebuilt in full quality through the API: a full video is a new generation, and the scene may come out differently. - Type: String - Allowed values: `full`, `draft` - Default: `"full"` #### `resolution` (Optional) Quality of a full video: HD or Full HD, Full HD costs more. A draft is always HD, this field does not apply to it. - Type: String - Allowed values: `hd`, `fhd` (Full HD) - Default: `"hd"` #### `aspect_ratio` (Optional) Aspect ratio. Auto: the model picks it itself, from the frames or the source clip. - Type: String - Allowed values: `auto`, `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` - Default: `"9:16"` #### `audio` (Optional) With sound or silent. The model writes speech, effects and ambience in the same run, the sound is not billed separately. - Type: String - Allowed values: `on` (With sound), `off` (Silent) - Default: `"on"` #### `duration` (Optional) Video length in seconds, 5 to 20. The price is per second, so it grows with the length. - Type: Integer - Minimum: 5 - Maximum: 20 - Default: `5` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A video from a description ```json { "model": "flux3", "settings": { "mode": "t2v", "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки", "aspect_ratio": "16:9", "duration": 8 } } ``` A draft to check the idea ```json { "model": "flux3", "settings": { "mode": "t2v", "prompt": "Бармен подбрасывает шейкер, ловит его за спиной и говорит: «Ваш коктейль»", "render": "draft", "duration": 6 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, 24 frames per second, with sound unless it is turned off. - Generation takes 1 to 10 minutes depending on length and quality. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From frames > Your pictures become frames of the video: one opens the clip, two set the start and the end, more than two are spread evenly from start to finish. Value of the mode field: `i2v` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the scene, the camera movement, the sounds. Spoken lines and on-screen text can be described too. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `render` (Optional) A full video or a draft. A draft is faster, always HD and costs about a third of a full video. A draft cannot be rebuilt in full quality through the API: a full video is a new generation, and the scene may come out differently. - Type: String - Allowed values: `full`, `draft` - Default: `"full"` #### `resolution` (Optional) Quality of a full video: HD or Full HD, Full HD costs more. A draft is always HD, this field does not apply to it. - Type: String - Allowed values: `hd`, `fhd` (Full HD) - Default: `"hd"` #### `aspect_ratio` (Optional) Aspect ratio. Auto by default: the model picks it from your frames. - Type: String - Allowed values: `auto`, `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` - Default: `"auto"` #### `audio` (Optional) With sound or silent. The model writes speech, effects and ambience in the same run, the sound is not billed separately. - Type: String - Allowed values: `on` (With sound), `off` (Silent) - Default: `"on"` #### `duration` (Optional) Video length in seconds, 5 to 20. The price is per second, so it grows with the length. - Type: Integer - Minimum: 5 - Maximum: 20 - Default: `5` #### `image_urls` (Required) One to ten frame URLs, in order. - Type: List (String, uri) - Maximum items: 10 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - Frames are URLs of JPEG, PNG or WebP images, each at least 256 by 256 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 10 | | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a frame ```json { "model": "flux3", "settings": { "mode": "i2v", "prompt": "Камера медленно наезжает, листья шевелятся на ветру", "image_urls": [ "https://example.com/first-frame.jpg" ] } } ``` Start and end ```json { "model": "flux3", "settings": { "mode": "i2v", "prompt": "Бутон распускается в цветок, капли росы блестят на солнце", "aspect_ratio": "1:1", "duration": 6, "image_urls": [ "https://example.com/bud.png", "https://example.com/flower.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, 24 frames per second, with sound unless it is turned off. - Generation takes 1 to 10 minutes depending on length and quality. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video continuation > The model continues your clip from its last frames. The source is not part of the result. Noticeably more expensive than the other modes. Value of the mode field: `v2v` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video: the scene, the camera movement, the sounds. Spoken lines and on-screen text can be described too. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `render` (Optional) A full video or a draft. A draft is faster, always HD and costs about a third of a full video. A draft cannot be rebuilt in full quality through the API: a full video is a new generation, and the scene may come out differently. - Type: String - Allowed values: `full`, `draft` - Default: `"full"` #### `resolution` (Optional) Quality of a full video: HD or Full HD, Full HD costs more. A draft is always HD, this field does not apply to it. - Type: String - Allowed values: `hd`, `fhd` (Full HD) - Default: `"hd"` #### `aspect_ratio` (Optional) Aspect ratio. Auto by default: the continuation keeps the aspect ratio of the source clip, so the join is clean. - Type: String - Allowed values: `auto`, `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` - Default: `"auto"` #### `audio` (Optional) With sound or silent. The model writes speech, effects and ambience in the same run, the sound is not billed separately. - Type: String - Allowed values: `on` (With sound), `off` (Silent) - Default: `"on"` #### `duration` (Optional) Video length in seconds, 5 to 15. The price is per second, so it grows with the length. - Type: Integer - Minimum: 5 - Maximum: 15 - Default: `5` #### `video_urls` (Required) One URL of the MP4 clip to continue. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The clip is a URL of an MP4 file up to 50 MB and no longer than 60 seconds. It is sent whole, there is no trimming: cut it beforehand if needed. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4 | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Continue a clip ```json { "model": "flux3", "settings": { "mode": "v2v", "prompt": "Машина уходит в поворот, из-под колёс летит гравий, камера догоняет её", "duration": 5, "video_urls": [ "https://example.com/clip.mp4" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video, 24 frames per second, with sound unless it is turned off. - Generation takes 1 to 10 minutes depending on length and quality. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [FLUX 3: features and prices](https://api.cyhub.ai/models/flux-3) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Vidu Q3 API > Vidu Q3 video with sound, up to 16 seconds and up to 1080p: from a description, from one frame, from the first and last frames or from references. Developer: ShengShu Model key in the API: `vidu` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "vidu", "settings": { "mode": "t2v", "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»", "tier": "turbo", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "vidu", "settings": { "mode": "t2v", "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»", "tier": "turbo", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "vidu", "settings": { "mode": "t2v", "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»", "tier": "turbo", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "vidu", "settings": { "mode": "t2v", "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»", "tier": "turbo", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A video from text alone, no pictures are sent. Value of the mode field: `t2v` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the frame, who is in it, how the camera moves, what can be heard. Lines of the characters can be written right in the description, the lips will match. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `audio` (Optional) With sound (speech, effects and ambience) or silent. Sound costs nothing extra. - Type: String - Allowed values: `on` (With sound), `off` (Silent) - Default: `"on"` #### `tier` (Optional) Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it. - Type: String - Allowed values: `turbo`, `pro` - Default: `"turbo"` #### `resolution` (Optional) Video quality. The price is per second and depends on the quality. - Type: String - Allowed values: `540p`, `720p`, `1080p` - The set depends on `tier`. - Default: `"720p"` #### `duration` (Optional) Length in seconds, 1 to 16. The price is per second. - Type: Integer - Minimum: 1 - Maximum: 16 - Default: `5` #### `aspect_ratio` (Optional) Frame aspect ratio. - Type: String - Allowed values: `16:9`, `9:16`, `4:3`, `3:4`, `1:1` - Default: `"9:16"` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - A description is needed in every mode. - The price is per second of the clip and depends on the mode, speed and quality. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A video from a description ```json { "model": "vidu", "settings": { "mode": "t2v", "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»", "tier": "turbo", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 1 to 10 minutes depending on length and quality. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Animate a frame > The model sets a picture in motion by the description, keeping what is on it. The video takes the aspect ratio of the picture. Value of the mode field: `i2v` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the frame, who is in it, how the camera moves, what can be heard. Lines of the characters can be written right in the description, the lips will match. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `audio` (Optional) With sound (speech, effects and ambience) or silent. Sound costs nothing extra. - Type: String - Allowed values: `on` (With sound), `off` (Silent) - Default: `"on"` #### `tier` (Optional) Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it. - Type: String - Allowed values: `turbo`, `pro` - Default: `"turbo"` #### `resolution` (Optional) Video quality. The price is per second and depends on the quality. - Type: String - Allowed values: `540p`, `720p`, `1080p` - The set depends on `tier`. - Default: `"720p"` #### `duration` (Optional) Length in seconds, 1 to 16. The price is per second. - Type: Integer - Minimum: 1 - Maximum: 16 - Default: `5` #### `image_urls` (Required) One URL of the picture to animate. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - A description is needed in every mode. - The price is per second of the clip and depends on the mode, speed and quality. - Images are URLs of JPEG, PNG or WebP files up to 50 MB each. - One side of a picture cannot be more than 4 times longer than the other. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a photo ```json { "model": "vidu", "settings": { "mode": "i2v", "prompt": "Кот поворачивает голову к камере и громко мяукает", "image_urls": [ "https://example.com/cat.jpg" ], "duration": 5 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 1 to 10 minutes depending on length and quality. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## First and last frame > Two pictures: where the video starts and where it ends, the model invents the transition. The video takes the aspect ratio of the frames. Value of the mode field: `se2v` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the frame, who is in it, how the camera moves, what can be heard. Lines of the characters can be written right in the description, the lips will match. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `audio` (Optional) With sound (speech, effects and ambience) or silent. Sound costs nothing extra. - Type: String - Allowed values: `on` (With sound), `off` (Silent) - Default: `"on"` #### `tier` (Optional) Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it. - Type: String - Allowed values: `turbo`, `pro` - Default: `"turbo"` #### `resolution` (Optional) Video quality. The price is per second and depends on the quality. - Type: String - Allowed values: `540p`, `720p`, `1080p` - The set depends on `tier`. - Default: `"720p"` #### `duration` (Optional) Length in seconds, 1 to 16. The price is per second. - Type: Integer - Minimum: 1 - Maximum: 16 - Default: `5` #### `image_urls` (Required) Exactly two URLs in order: the first is the starting frame, the second is the ending frame. - Type: List (String, uri) - Maximum items: 2 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - A description is needed in every mode. - The price is per second of the clip and depends on the mode, speed and quality. - Images are URLs of JPEG, PNG or WebP files up to 50 MB each. - The aspect ratios of the two frames must be close: they differ by no more than 1.25 times. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 2 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A transition between frames ```json { "model": "vidu", "settings": { "mode": "se2v", "prompt": "Утро плавно сменяется ночью, камера стоит на месте", "image_urls": [ "https://example.com/first.jpg", "https://example.com/last.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 1 to 10 minutes depending on length and quality. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Up to seven pictures: characters, objects, clothes, settings, style. The model builds a scene from them and keeps them consistent through the clip. The length is 3 seconds or more. Value of the mode field: `r2v` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the frame, who is in it, how the camera moves, what can be heard. Lines of the characters can be written right in the description, the lips will match. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `audio` (Optional) With sound (speech, effects and ambience) or silent. Sound costs nothing extra. - Type: String - Allowed values: `on` (With sound), `off` (Silent) - Default: `"on"` #### `tier` (Optional) Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it. Mix gives the best picture, costs more than Pro and has no 540p. - Type: String - Allowed values: `turbo`, `pro`, `mix` - Default: `"turbo"` #### `resolution` (Optional) Video quality. The price is per second and depends on the quality. - Type: String - Allowed values: `540p`, `720p`, `1080p` - The set depends on `tier`. - Exceptions: | `tier` | `resolution` | |---|---| | `mix` | except `540p` | - Default: `"720p"` #### `duration` (Optional) Length in seconds, 3 to 16. The price is per second. - Type: Integer - Minimum: 3 - Maximum: 16 - Default: `5` #### `aspect_ratio` (Optional) Frame aspect ratio. - Type: String - Allowed values: `16:9`, `9:16`, `1:1` - Default: `"9:16"` #### `image_urls` (Required) One to seven URLs of pictures with what must be in the video. - Type: List (String, uri) - Maximum items: 7 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - A description is needed in every mode. - The price is per second of the clip and depends on the mode, speed and quality. - Images are URLs of JPEG, PNG or WebP files up to 50 MB each. - One side of a picture cannot be more than 4 times longer than the other. - Every picture is at least 128 by 128 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 7 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A character and an object from pictures ```json { "model": "vidu", "settings": { "mode": "r2v", "prompt": "Девушка с первой картинки в куртке со второй идёт по ночной набережной", "tier": "pro", "resolution": "720p", "aspect_ratio": "9:16", "duration": 6, "image_urls": [ "https://example.com/girl.png", "https://example.com/jacket.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 1 to 10 minutes depending on length and quality. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Vidu Q3: features and prices](https://api.cyhub.ai/models/vidu-q3) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # HappyHorse 1.1 API > HappyHorse video: from a prompt, from a picture, from reference pictures, or an edit of a finished clip. Developer: Alibaba Model key in the API: `happyhorse` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "happyhorse", "settings": { "mode": "text_to_video", "prompt": "Лошадь скачет по полю на закате, камера движется рядом", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "happyhorse", "settings": { "mode": "text_to_video", "prompt": "Лошадь скачет по полю на закате, камера движется рядом", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "happyhorse", "settings": { "mode": "text_to_video", "prompt": "Лошадь скачет по полю на закате, камера движется рядом", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "happyhorse", "settings": { "mode": "text_to_video", "prompt": "Лошадь скачет по полю на закате, камера движется рядом", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a prompt > Video from text alone, no pictures are sent. Value of the mode field: `text_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Any language works, Chinese text is limited to 2,500 characters. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `resolution` (Optional) Resolution of the finished video; the price depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `aspect_ratio` (Optional) Frame shape: landscape, portrait, square or the classic 4:3 and 3:4. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - Default: `"9:16"` #### `duration` (Optional) Video length in seconds, 3 to 15. The price is per second. - Type: Integer - Minimum: 3 - Maximum: 15 - Default: `5` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Video from a prompt ```json { "model": "happyhorse", "settings": { "mode": "text_to_video", "prompt": "Лошадь скачет по полю на закате, камера движется рядом", "resolution": "720p", "aspect_ratio": "16:9", "duration": 5 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 3 to 15 minutes, longer for long clips. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From a picture > The picture becomes the first frame, the model animates it by the prompt. The video takes the shape of the picture. Value of the mode field: `image_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Any language works, Chinese text is limited to 2,500 characters. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `resolution` (Optional) Resolution of the finished video; the price depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `image_urls` (Required) One URL of the picture for the first frame. - Type: List (String, uri) - Maximum items: 1 #### `duration` (Optional) Video length in seconds, 3 to 15. The price is per second. - Type: Integer - Minimum: 3 - Maximum: 15 - Default: `5` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 20 MB, each side at least 300 pixels, shape from 1:2.5 to 2.5:1. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Animate a picture ```json { "model": "happyhorse", "settings": { "mode": "image_to_video", "prompt": "Камера медленно наезжает, волосы героини развеваются на ветру", "image_urls": [ "https://example.com/first-frame.jpg" ], "duration": 5 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 3 to 15 minutes, longer for long clips. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From references > Characters, objects and settings from your pictures in a new video. Value of the mode field: `reference_to_video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What happens in the video. Any language works, Chinese text is limited to 2,500 characters. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `resolution` (Optional) Resolution of the finished video; the price depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `reference_image_urls` (Required) 1 to 9 URLs of pictures with the characters, objects or setting. - Type: List (String, uri) - Maximum items: 9 #### `aspect_ratio` (Optional) Frame shape: landscape, portrait, square or the classic 4:3 and 3:4. - Type: String - Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4` - Default: `"9:16"` #### `duration` (Optional) Video length in seconds, 3 to 15. The price is per second. - Type: Integer - Minimum: 3 - Maximum: 15 - Default: `5` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Pictures are URLs of JPEG, PNG or WebP files up to 20 MB each, the short side at least 400 pixels. - The prompt can refer to the pictures in the order of the URLs: [Image 1], [Image 2] and so on. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `reference_image_urls` | Images | jpeg, jpg, png, webp | 9 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A character from a picture ```json { "model": "happyhorse", "settings": { "mode": "reference_to_video", "prompt": "Женщина с [Image 1] идёт по ночному городу под дождём", "reference_image_urls": [ "https://example.com/woman.png" ], "aspect_ratio": "9:16", "duration": 5 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 3 to 15 minutes, longer for long clips. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Video editing > A finished clip is changed by the prompt: other clothes, style, objects. Runs on version 1.0, so a second costs more here. Value of the mode field: `video_edit` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to change in the clip, for example "dress the hero in the sweater from the picture". Any language works, Chinese text is limited to 2,500 characters. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `resolution` (Optional) Resolution of the finished video; the price depends on it. - Type: String - Allowed values: `720p`, `1080p` - Default: `"720p"` #### `video_url` (Required) One URL of the clip to change. - Type: List (String, uri) - Maximum items: 1 #### `reference_image_urls` (Optional) Up to 5 URLs of pictures with what to add to the clip. Optional. - Type: List (String, uri) - Maximum items: 5 #### `audio_setting` (Optional) Sound of the result: new sound matched to the changed video, or the sound of the source clip. - Type: String - Allowed values: `auto`, `origin` - Default: `"auto"` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The video is a URL of an MP4 or MOV file up to 100 MB, 3 to 60 seconds long, sides from 320 to 2160 pixels, shape from 1:2.5 to 2.5:1, more than 8 frames per second. - The whole clip goes to the model. The price follows its length: the seconds of the source and as many again for the result, a part of a second counts as a whole one. - Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, each side at least 300 pixels, shape from 1:2.5 to 2.5:1. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_url` | Video | mp4, mov | 1 | 100 MB | | `reference_image_urls` | Images | jpeg, jpg, png, webp | 5 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Change the hero's clothes ```json { "model": "happyhorse", "settings": { "mode": "video_edit", "prompt": "Надень на героя полосатый свитер с картинки", "video_url": [ "https://example.com/clip.mp4" ], "reference_image_urls": [ "https://example.com/sweater.png" ], "audio_setting": "origin" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One MP4 video. - Generation takes 3 to 15 minutes, longer for long clips. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [HappyHorse 1.1: features and prices](https://api.cyhub.ai/models/happyhorse) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # HeyGen Lip Sync API > HeyGen LipSync: a new audio track for an existing video, the lips of the person on screen move to it. Developer: HeyGen Model key in the API: `heygen` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4" ], "audio_url": [ "https://example.com/new_voice.mp3" ] } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4", ], "audio_url": [ "https://example.com/new_voice.mp3", ], }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4" ], "audio_url": [ "https://example.com/new_voice.mp3" ] } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4" ], "audio_url": [ "https://example.com/new_voice.mp3" ] } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Parameters Model parameters go inside settings. Omitted optional fields take their default values. ### `mode` (Optional) Quality. Speed suits a face that barely moves. Precision handles head turns, movement and a partly covered face better, takes longer and costs more. - Type: String - Allowed values: `speed`, `precision` - Default: `"speed"` ### `video_url` (Required) One URL of the source video. The speaker's face must be clearly visible, and the video must have its own audio track with speech. - Type: List (String, uri) - Maximum items: 1 ### `audio_url` (Required) One URL of the new audio track: the lips move to it. - Type: List (String, uri) - Maximum items: 1 ### `enable_dynamic_duration` (Optional) Fit the length of the finished video to the audio. On: the audio and video lengths must differ by at most 15%, otherwise HeyGen refuses. Off: the video keeps its own length. - Type: Boolean - Default: `true` ### `disable_music_track` (Optional) Remove the background music from the source video. - Type: Boolean - Default: `false` ### `enable_speech_enhancement` (Optional) Improve how the speech sounds in the finished video. - Type: Boolean - Default: `false` ### `keep_the_same_format` (Optional) Keep the resolution and bitrate of the source video. - Type: Boolean - Default: `true` ### `enable_watermark` (Optional) Put a HeyGen watermark on the finished video. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ## Input - The video is a URL of an MP4, MOV or WebM file up to 200 MB, the audio is a URL of an MP3, WAV, M4A, OGG or FLAC file up to 50 MB. The video is at most 10 minutes long, the audio at most 10 minutes. - The URLs must be public and start with https://: HeyGen downloads the files itself. - The source video needs its own audio track with speech: HeyGen uses it to find who speaks and when. It does not accept a video without sound or with silence. - The video goes to HeyGen whole, and the price follows its full length in seconds. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_url` | Video | mp4, mov, webm | 1 | 200 MB | | `audio_url` | Audio | mp3, wav, m4a, ogg, flac | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ## Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. New voice-over for a video ```json { "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4" ], "audio_url": [ "https://example.com/new_voice.mp3" ] } } ``` Precision mode, the video keeps its length ```json { "model": "heygen", "settings": { "mode": "precision", "video_url": [ "https://example.com/interview.mov" ], "audio_url": [ "https://example.com/dub.wav" ], "enable_dynamic_duration": false, "disable_music_track": true } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ## Output - One video with the new audio track. - Processing usually takes a few minutes, occasionally up to half an hour. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [HeyGen Lip Sync: features and prices](https://api.cyhub.ai/models/heygen-lip-sync) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Seedream 5.0 API > Seedream 5.0 images from a prompt and reference pictures (up to 14), 2K or 3K quality. PNG or JPEG output. Developer: ByteDance Model key in the API: `seedream` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedream", "settings": { "mode": "5.0", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "3:4", "quality": "3K", "output_format": "png" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "seedream", "settings": { "mode": "5.0", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "3:4", "quality": "3K", "output_format": "png", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "seedream", "settings": { "mode": "5.0", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "3:4", "quality": "3K", "output_format": "png" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedream", "settings": { "mode": "5.0", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "3:4", "quality": "3K", "output_format": "png" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Seedream 5.0 > 2K or 3K quality, up to 14 references, PNG or JPEG result. Value of the mode field: `5.0` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw, or what to do with the reference images. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `image_urls` (Optional) Reference image URLs, up to 14. Without them the image is drawn from the prompt alone. - Type: List (String, uri) - Maximum items: 14 #### `aspect_ratio` (Optional) Aspect ratio. - Type: String - Allowed values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9` - Default: `"9:16"` #### `quality` (Optional) Image quality: 2K or 3K. - Type: String - Allowed values: `2K`, `3K` - Default: `"2K"` #### `output_format` (Optional) Result file format. - Type: String - Allowed values: `png`, `jpeg` - Default: `"png"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `model_version` = `"5.0"` ### Input - References are URLs of JPEG, PNG, WebP, BMP, TIFF or GIF images, up to 30 MB each. - Each picture has both sides longer than 14 pixels, an area of at most 6000×6000 pixels, and one side at most 16 times longer than the other. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, tif, gif | 14 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. An image from a prompt ```json { "model": "seedream", "settings": { "mode": "5.0", "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах", "aspect_ratio": "3:4", "quality": "3K", "output_format": "png" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One image per run in the chosen format. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg | 1 | The format is set by output_format. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Seedream 5.0: features and prices](https://api.cyhub.ai/models/seedream-5) - Other versions: [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md), [Seedream 4.5 API](https://api.cyhub.ai/en/models/seedream-4-5/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Seedream 5.0 PRO API > Seedream 5.0 PRO images from a prompt and reference pictures (up to 10), 1K or 2K quality. It also splits a picture into layers with transparency and edits a PNG with a transparent background keeping the transparency. Developer: ByteDance Model key in the API: `seedream` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedream", "settings": { "mode": "5.0_pro", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "21:9", "quality": "2K" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "seedream", "settings": { "mode": "5.0_pro", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "21:9", "quality": "2K", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "seedream", "settings": { "mode": "5.0_pro", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "21:9", "quality": "2K" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedream", "settings": { "mode": "5.0_pro", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "21:9", "quality": "2K" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Seedream 5.0 PRO > The newest version: 1K or 2K quality, up to 10 references. Every reference after the first one adds a little to the price. Value of the mode field: `5.0_pro` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw, or what to do with the reference images. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `image_urls` (Optional) Reference image URLs, up to 10. Without them the image is drawn from the prompt alone. - Type: List (String, uri) - Maximum items: 10 #### `aspect_ratio` (Optional) Aspect ratio. - Type: String - Allowed values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9` - Default: `"9:16"` #### `quality` (Optional) Image quality: 1K or 2K. The price depends on it. - Type: String - Allowed values: `1K`, `2K` - Default: `"1K"` #### `output_format` (Optional) Result file format. - Type: String - Allowed values: `png`, `jpeg` - Default: `"png"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `model_version` = `"5.0_pro"` ### Input - References are URLs of JPEG, PNG, WebP, BMP, TIFF or GIF images, up to 30 MB each. - Each picture has both sides longer than 14 pixels, an area of at most 6000×6000 pixels, and one side at most 16 times longer than the other. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, tif, gif | 10 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Wide image in 2K ```json { "model": "seedream", "settings": { "mode": "5.0_pro", "prompt": "Горный хребет на рассвете, туман в долинах", "aspect_ratio": "21:9", "quality": "2K" } } ``` A character from a reference ```json { "model": "seedream", "settings": { "mode": "5.0_pro", "prompt": "Этот персонаж на обложке журнала о путешествиях", "image_urls": [ "https://example.com/character.png" ], "aspect_ratio": "3:4" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One image per run in the chosen format. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg | 1 | The format is set by output_format. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Split into layers > Version 5.0 PRO takes one picture apart: the base without the extracted elements and every noticeable element as its own PNG with transparency. The model decides how many parts come out. The price shown is the ceiling, the charge covers only the files that come back. Value of the mode field: `layers` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the picture to split. - Type: List (String, uri) - Maximum items: 1 #### `prompt` (Optional) What to take out, in words, for example "the cat and the caption on top". A part can also be pointed at with a frame x1 y1 x2 y2: the top left and bottom right corners in fractions of the picture from 0 to 1000. Without a description the model finds every noticeable element itself. - Type: String - Maximum characters: 5000 #### `quality` (Optional) Size of the base and the layers. 1K and 1.5K cost the same, 1.5K gives larger files. 2K costs more. - Type: String - Allowed values: `1K`, `1.5K`, `2K` - Default: `"1.5K"` #### `output_format` (Optional) Format of the base. Layers are always PNG. - Type: String - Allowed values: `png`, `jpeg` - Default: `"png"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `model_version` = `"5.0_pro"`, `layer_decomposition` = `true` ### Input - One JPEG or PNG picture up to 30 MB, with an area from 512×512 to 6000×6000 pixels and one side at most 16 times longer than the other. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png | 1 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Split the whole picture ```json { "model": "seedream", "settings": { "mode": "layers", "image_urls": [ "https://example.com/poster.png" ] } } ``` Take out the named elements ```json { "model": "seedream", "settings": { "mode": "layers", "image_urls": [ "https://example.com/poster.png" ], "prompt": "Кот и надпись сверху", "quality": "2K" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - The base as an image and a ZIP archive: the base, every layer as its own PNG with transparency, the frame assembled from the layers and a list of layers named by the model. - There are from one to sixteen layers. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg | 1 | The base; the format is set by output_format. | | `document` | zip | 1 | An archive: the base, every layer as its own PNG, the frame assembled from the layers and the list of layers. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.zip", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Edit keeping transparency > Version 5.0 PRO edits a PNG picture with a transparent background and keeps the transparency. An ordinary photo cannot be made transparent this way: splitting into layers is for that. Value of the mode field: `keep_transparency` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to change in the picture. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `image_urls` (Required) One URL of a PNG that already has transparent areas. - Type: List (String, uri) - Maximum items: 1 #### `aspect_ratio` (Optional) Aspect ratio. - Type: String - Allowed values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9` - Default: `"9:16"` #### `quality` (Optional) Image quality: 1K or 2K. The price depends on it. - Type: String - Allowed values: `1K`, `2K` - Default: `"1K"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `model_version` = `"5.0_pro"`, `keep_transparency` = `true`, `output_format` = `"png"` ### Input - One PNG picture up to 30 MB that already has transparent areas. - Each picture has both sides longer than 14 pixels, an area of at most 6000×6000 pixels, and one side at most 16 times longer than the other. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | png | 1 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Recolor a logo without a background ```json { "model": "seedream", "settings": { "mode": "keep_transparency", "prompt": "Сделай логотип синим, форму не меняй", "image_urls": [ "https://example.com/logo.png" ], "aspect_ratio": "1:1" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One PNG image with a transparent background. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Seedream 5.0 PRO: features and prices](https://api.cyhub.ai/models/seedream-5-pro) - Other versions: [Seedream 5.0 API](https://api.cyhub.ai/en/models/seedream-5/api.md), [Seedream 4.5 API](https://api.cyhub.ai/en/models/seedream-4-5/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Seedream 4.5 API > Seedream 4.5 images from a prompt and reference pictures (up to 14), 2K or 4K quality. The previous version, the result is always JPEG. Developer: ByteDance Model key in the API: `seedream` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedream", "settings": { "mode": "4.5", "prompt": "Маяк на скале в шторм, кинематографичный свет", "aspect_ratio": "16:9", "quality": "4K" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "seedream", "settings": { "mode": "4.5", "prompt": "Маяк на скале в шторм, кинематографичный свет", "aspect_ratio": "16:9", "quality": "4K", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "seedream", "settings": { "mode": "4.5", "prompt": "Маяк на скале в шторм, кинематографичный свет", "aspect_ratio": "16:9", "quality": "4K" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "seedream", "settings": { "mode": "4.5", "prompt": "Маяк на скале в шторм, кинематографичный свет", "aspect_ratio": "16:9", "quality": "4K" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Seedream 4.5 > The previous version: 2K or 4K quality, up to 14 references. The result is always JPEG. Value of the mode field: `4.5` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw, or what to do with the reference images. - Type: String - Minimum characters: 1 - Maximum characters: 5000 #### `image_urls` (Optional) Reference image URLs, up to 14. Without them the image is drawn from the prompt alone. - Type: List (String, uri) - Maximum items: 14 #### `aspect_ratio` (Optional) Aspect ratio. - Type: String - Allowed values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9` - Default: `"9:16"` #### `quality` (Optional) Image quality: 2K or 4K. - Type: String - Allowed values: `2K`, `4K` - Default: `"2K"` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `model_version` = `"4.5"`, `output_format` = `"jpeg"` ### Input - References are URLs of JPEG, PNG, WebP, BMP, TIFF or GIF images, up to 30 MB each. - Each picture has both sides longer than 14 pixels, an area of at most 6000×6000 pixels, and one side at most 16 times longer than the other. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp, bmp, tiff, tif, gif | 14 | 30 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. An image in 4K ```json { "model": "seedream", "settings": { "mode": "4.5", "prompt": "Маяк на скале в шторм, кинематографичный свет", "aspect_ratio": "16:9", "quality": "4K" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - One JPEG image per run. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | jpg | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.jpg", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Seedream 4.5: features and prices](https://api.cyhub.ai/models/seedream-4-5) - Other versions: [Seedream 5.0 API](https://api.cyhub.ai/en/models/seedream-5/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Recraft API > Recraft pictures and real SVG vectors from a description, versions V4.1 and V4.1 Pro. Edits of your picture: replacing and erasing an area by a mask, extending the frame, replacing the background. Also similar variants, conversion to vector, background removal and upscaling. Developer: Recraft Model key in the API: `recraft` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v4_1", "aspect_ratio": "3:2" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v4_1", "aspect_ratio": "3:2", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v4_1", "aspect_ratio": "3:2" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v4_1", "aspect_ratio": "3:2" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Picture from a description > Draws a picture from scratch by the description. Recraft handles in-frame text well. Value of the mode field: `text_to_image` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Put the words that must appear on the picture in quotes. With the V3 and V2 engines no longer than 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 2000 #### `engine` (Optional) Engine; the price depends on it. V4.1: the best balance. V4.1 Pro: top quality, larger (a 2048 by 2048 square instead of 1024 by 1024) and noticeably pricier. V3: supports preset styles. V2: the cheapest. - Type: String - Allowed values: `v4_1` (V4.1 (best balance)), `v4_1_pro` (V4.1 Pro (top quality)) - Default: `"v4_1"` #### `style` (Optional) A preset style: photorealism or illustration. Only V3 and V2 have them; with V4.1 describe the manner in words. - Type: String - Allowed values: `none` - The set depends on `engine`. - Default: `"none"` #### `aspect_ratio` (Optional) Aspect ratio of the frame. - Type: String - Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2` - Default: `"1:1"` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A sign with lettering ```json { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v4_1", "aspect_ratio": "3:2" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Vector from a description > Draws a real SVG vector from scratch: logos, icons, flat illustrations. Value of the mode field: `text_to_vector` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Put the words that must appear on the picture in quotes. With the V3 and V2 engines no longer than 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 2000 #### `engine` (Optional) Engine; the price depends on it. V4.1: the best balance. V4.1 Pro: top quality, noticeably pricier. V3: the previous generation. V2: the cheapest. - Type: String - Allowed values: `v4_1` (V4.1 (best balance)), `v4_1_pro` (V4.1 Pro (top quality)) - Default: `"v4_1"` #### `aspect_ratio` (Optional) Aspect ratio of the frame. - Type: String - Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2` - Default: `"1:1"` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. An icon ```json { "model": "recraft", "settings": { "mode": "text_to_vector", "prompt": "Плоская иконка ракеты в два цвета, толстый контур", "engine": "v4_1", "aspect_ratio": "1:1" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The result is SVG: a real vector that scales without loss and opens in an editor. As many files as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `document` | svg | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "document", "filename": "result.svg", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Rework a picture > Your picture plus a description: the model draws a new one keeping the composition and colours of the source. strength sets how far to go. Value of the mode field: `image_to_image` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 #### `prompt` (Required) What the picture should become, up to 1000 characters. Name the objects: the model draws by the description and does not get references like "the same object". - Type: String - Minimum characters: 1 - Maximum characters: 1000 #### `strength` (Optional) How far to go from the source: 0.2 a light touch, 0.5 a noticeable rework, 0.8 almost from scratch. - Type: String - Allowed values: `0.2` (Light touch), `0.5` (Noticeable rework), `0.8` (Almost from scratch) - Default: `"0.5"` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A different interior ```json { "model": "recraft", "settings": { "mode": "image_to_image", "image_urls": [ "https://example.com/living-room.jpg" ], "prompt": "Гостиная в скандинавском стиле: светлый диван, дубовый стол, растения в горшках", "strength": "0.5" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Replace an area > Repaints the part of the picture marked by the mask according to the description. The rest stays as it was. Value of the mode field: `inpaint` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 #### `mask_urls` (Required) One URL of the mask: a grayscale picture of exactly the same size as the source. White marks what to repaint, black marks what to keep. - Type: List (String, uri) - Maximum items: 1 #### `prompt` (Required) A description of the whole picture as it should end up, not just the marked piece, up to 1000 characters. A short order like "write GG here" will only wipe the area. - Type: String - Minimum characters: 1 - Maximum characters: 1000 #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. - Mask: a grayscale PNG or JPEG (one channel, no colour or transparency) of exactly the same size as the source. White marks what changes, black marks what stays. A colour mask will not do, even if it looks black and white. - PNG is better: only pure black and pure white are expected, and JPEG compression leaves grey pixels on the edges. - We download the picture and the mask ourselves: the URL must return the file directly, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | | `mask_urls` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A cactus on the windowsill ```json { "model": "recraft", "settings": { "mode": "inpaint", "image_urls": [ "https://example.com/room.jpg" ], "mask_urls": [ "https://example.com/room-mask.png" ], "prompt": "Светлая комната, на подоконнике стоит глиняный горшок с кактусом" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Erase something > Removes what the mask marks and fills in the background behind it. No description needed. Value of the mode field: `erase` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 #### `mask_urls` (Required) One URL of the mask: a grayscale picture of exactly the same size as the source. White marks what to erase, black marks what to keep. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. - Mask: a grayscale PNG or JPEG (one channel, no colour or transparency) of exactly the same size as the source. White marks what changes, black marks what stays. A colour mask will not do, even if it looks black and white. - PNG is better: only pure black and pure white are expected, and JPEG compression leaves grey pixels on the edges. - We download the picture and the mask ourselves: the URL must return the file directly, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | | `mask_urls` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Remove a passer-by ```json { "model": "recraft", "settings": { "mode": "erase", "image_urls": [ "https://example.com/beach.jpg" ], "mask_urls": [ "https://example.com/beach-mask.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The picture comes as a lossless WebP file. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Extend the frame > Draws the picture further out by the given number of pixels. Value of the mode field: `outpaint` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 #### `prompt` (Required) What should appear in the added part, up to 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 1000 #### `expand_left` (Optional) How many pixels to add on the left, 0 to 1024. - Type: Integer - Minimum: 0 - Maximum: 1024 - Default: `0` #### `expand_right` (Optional) How many pixels to add on the right, 0 to 1024. - Type: Integer - Minimum: 0 - Maximum: 1024 - Default: `0` #### `expand_top` (Optional) How many pixels to add on the top, 0 to 1024. - Type: Integer - Minimum: 0 - Maximum: 1024 - Default: `0` #### `expand_bottom` (Optional) How many pixels to add on the bottom, 0 to 1024. - Type: Integer - Minimum: 0 - Maximum: 1024 - Default: `0` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. - At least one side above zero. The final frame is at most 4096 pixels on each side. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Wider on both sides ```json { "model": "recraft", "settings": { "mode": "outpaint", "image_urls": [ "https://example.com/portrait.jpg" ], "prompt": "Песчаный пляж и спокойное море до горизонта", "expand_left": 512, "expand_right": 512 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Replace the background > The object stays, and Recraft finds the background itself and rewrites it by the description. Value of the mode field: `replace_background` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 #### `prompt` (Required) What the background should become, up to 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 1000 #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A product on marble ```json { "model": "recraft", "settings": { "mode": "replace_background", "image_urls": [ "https://example.com/bottle.png" ], "prompt": "Мраморная столешница, мягкий утренний свет" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Background by mask > Like replacing the background, but the mask sets where the background is. Value of the mode field: `generate_background` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 #### `mask_urls` (Required) One URL of the mask: a grayscale picture of exactly the same size as the source. White marks where to draw the new background, black marks the object that stays. - Type: List (String, uri) - Maximum items: 1 #### `prompt` (Required) What the background should become, up to 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 1000 #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. - Mask: a grayscale PNG or JPEG (one channel, no colour or transparency) of exactly the same size as the source. White marks what changes, black marks what stays. A colour mask will not do, even if it looks black and white. - PNG is better: only pure black and pure white are expected, and JPEG compression leaves grey pixels on the edges. - We download the picture and the mask ourselves: the URL must return the file directly, without a redirect. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | | `mask_urls` | Images | jpeg, jpg, png | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A sneaker by a wall ```json { "model": "recraft", "settings": { "mode": "generate_background", "image_urls": [ "https://example.com/sneaker.png" ], "mask_urls": [ "https://example.com/sneaker-mask.png" ], "prompt": "Бетонная стена с граффити, дневной свет" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Similar variants > A few variations of your picture: details, object positions and composition change, the overall idea stays. No description needed. Value of the mode field: `variate` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 #### `aspect_ratio` (Optional) Aspect ratio of the variants. - Type: String - Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2` - Default: `"1:1"` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Three variants of a character ```json { "model": "recraft", "settings": { "mode": "variate", "image_urls": [ "https://example.com/mascot.png" ], "aspect_ratio": "1:1", "count": 3 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Convert to vector > Turns the picture into a real SVG vector. No description needed. Value of the mode field: `vectorize` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A logo to vector ```json { "model": "recraft", "settings": { "mode": "vectorize", "image_urls": [ "https://example.com/logo.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The result is one SVG file. | Kind | Formats | How many | Note | |---|---|---|---| | `document` | svg | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "document", "filename": "result.svg", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Remove the background > Cuts out the object and removes the background. No description needed. Value of the mode field: `remove_background` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A product without background ```json { "model": "recraft", "settings": { "mode": "remove_background", "image_urls": [ "https://example.com/product.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - A picture with a transparent background, a lossless WebP file. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Crisp upscale > Makes the picture larger: lines stay sharp and nothing new appears. No description needed. Value of the mode field: `upscale_crisp` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 32 to 4096 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Enlarge a small picture ```json { "model": "recraft", "settings": { "mode": "upscale_crisp", "image_urls": [ "https://example.com/small.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The picture comes as a lossless WebP file. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Creative upscale > Makes the picture larger and invents fine details: skin pores, stray hairs, fabric grain. Saves small or blurry sources but may rewrite details its own way. No description needed. Value of the mode field: `upscale_creative` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `image_urls` (Required) One URL of the source picture. - Type: List (String, uri) - Maximum items: 1 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. An old photo made larger ```json { "model": "recraft", "settings": { "mode": "upscale_creative", "image_urls": [ "https://example.com/old-photo.jpg" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The picture comes as a lossless WebP file. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Recraft: features and prices](https://api.cyhub.ai/models/recraft) - Other versions: [Recraft V3 API](https://api.cyhub.ai/en/models/recraft-v3/api.md), [Recraft V2 API](https://api.cyhub.ai/en/models/recraft-v2/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Recraft V3 API > Recraft V3 pictures with preset styles and real SVG vectors from a description: logos, icons, flat illustrations. Styles: photorealism or illustration. Up to 6 results per run. Developer: Recraft Model key in the API: `recraft` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Чашка капучино на мраморном столе, утренний свет из окна", "engine": "v3", "style": "realistic_image", "count": 2 } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Чашка капучино на мраморном столе, утренний свет из окна", "engine": "v3", "style": "realistic_image", "count": 2, }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Чашка капучино на мраморном столе, утренний свет из окна", "engine": "v3", "style": "realistic_image", "count": 2 } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Чашка капучино на мраморном столе, утренний свет из окна", "engine": "v3", "style": "realistic_image", "count": 2 } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Picture from a description > Draws a picture from scratch by the description. Recraft handles in-frame text well. Value of the mode field: `text_to_image` This page is about Recraft V3: send engine = v3. Without the engine field the task runs on v4_1. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Put the words that must appear on the picture in quotes. With the V3 and V2 engines no longer than 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 2000 #### `engine` (Optional) Engine; the price depends on it. V4.1: the best balance. V4.1 Pro: top quality, larger (a 2048 by 2048 square instead of 1024 by 1024) and noticeably pricier. V3: supports preset styles. V2: the cheapest. - Type: String - Allowed values: `v3` - Default: `"v4_1"` #### `style` (Optional) A preset style: photorealism or illustration. Only V3 and V2 have them; with V4.1 describe the manner in words. - Type: String - Allowed values: `none` (No style), `realistic_image` (Realistic photo), `digital_illustration` (Digital illustration) - Default: `"none"` #### `aspect_ratio` (Optional) Aspect ratio of the frame. - Type: String - Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2` - Default: `"1:1"` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Photorealism on V3, two variants ```json { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Чашка капучино на мраморном столе, утренний свет из окна", "engine": "v3", "style": "realistic_image", "count": 2 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Vector from a description > Draws a real SVG vector from scratch: logos, icons, flat illustrations. Value of the mode field: `text_to_vector` This page is about Recraft V3: send engine = v3. Without the engine field the task runs on v4_1. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Put the words that must appear on the picture in quotes. With the V3 and V2 engines no longer than 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 2000 #### `engine` (Optional) Engine; the price depends on it. V4.1: the best balance. V4.1 Pro: top quality, noticeably pricier. V3: the previous generation. V2: the cheapest. - Type: String - Allowed values: `v3` - Default: `"v4_1"` #### `aspect_ratio` (Optional) Aspect ratio of the frame. - Type: String - Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2` - Default: `"1:1"` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. An icon ```json { "model": "recraft", "settings": { "mode": "text_to_vector", "prompt": "Плоская иконка ракеты в два цвета, толстый контур", "engine": "v3", "aspect_ratio": "1:1" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The result is SVG: a real vector that scales without loss and opens in an editor. As many files as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `document` | svg | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "document", "filename": "result.svg", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Recraft V3: features and prices](https://api.cyhub.ai/models/recraft-v3) - Other versions: [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md), [Recraft V2 API](https://api.cyhub.ai/en/models/recraft-v2/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Recraft V2 API > Recraft V2 pictures and real SVG vectors from a description: logos, icons, flat illustrations. The cheapest Recraft engine, with preset styles: photorealism or illustration. Up to 6 results per run. Developer: Recraft Model key in the API: `recraft` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v2", "aspect_ratio": "3:2" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v2", "aspect_ratio": "3:2", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v2", "aspect_ratio": "3:2" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v2", "aspect_ratio": "3:2" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Picture from a description > Draws a picture from scratch by the description. Recraft handles in-frame text well. Value of the mode field: `text_to_image` This page is about Recraft V2: send engine = v2. Without the engine field the task runs on v4_1. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Put the words that must appear on the picture in quotes. With the V3 and V2 engines no longer than 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 2000 #### `engine` (Optional) Engine; the price depends on it. V4.1: the best balance. V4.1 Pro: top quality, larger (a 2048 by 2048 square instead of 1024 by 1024) and noticeably pricier. V3: supports preset styles. V2: the cheapest. - Type: String - Allowed values: `v2` - Default: `"v4_1"` #### `style` (Optional) A preset style: photorealism or illustration. Only V3 and V2 have them; with V4.1 describe the manner in words. - Type: String - Allowed values: `none` (No style), `realistic_image` (Realistic photo), `digital_illustration` (Digital illustration) - Default: `"none"` #### `aspect_ratio` (Optional) Aspect ratio of the frame. - Type: String - Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2` - Default: `"1:1"` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A sign with lettering ```json { "model": "recraft", "settings": { "mode": "text_to_image", "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет", "engine": "v2", "aspect_ratio": "3:2" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The pictures come as lossless WebP files, as many as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | webp | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.webp", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Vector from a description > Draws a real SVG vector from scratch: logos, icons, flat illustrations. Value of the mode field: `text_to_vector` This page is about Recraft V2: send engine = v2. Without the engine field the task runs on v4_1. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What to draw. Put the words that must appear on the picture in quotes. With the V3 and V2 engines no longer than 1000 characters. - Type: String - Minimum characters: 1 - Maximum characters: 2000 #### `engine` (Optional) Engine; the price depends on it. V4.1: the best balance. V4.1 Pro: top quality, noticeably pricier. V3: the previous generation. V2: the cheapest. - Type: String - Allowed values: `v2` - Default: `"v4_1"` #### `aspect_ratio` (Optional) Aspect ratio of the frame. - Type: String - Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2` - Default: `"1:1"` #### `count` (Optional) How many variants to make at once, 1 to 6. Each one is paid separately. - Type: Integer - Minimum: 1 - Maximum: 6 - Default: `1` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. An icon ```json { "model": "recraft", "settings": { "mode": "text_to_vector", "prompt": "Плоская иконка ракеты в два цвета, толстый контур", "engine": "v2", "aspect_ratio": "1:1" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Usually ready in a few seconds to a minute. - The result is SVG: a real vector that scales without loss and opens in an editor. As many files as set in count. | Kind | Formats | How many | Note | |---|---|---|---| | `document` | svg | 1 to 6 | As many as set in count. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "document", "filename": "result.svg", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Recraft V2: features and prices](https://api.cyhub.ai/models/recraft-v2) - Other versions: [Recraft API](https://api.cyhub.ai/en/models/recraft/api.md), [Recraft V3 API](https://api.cyhub.ai/en/models/recraft-v3/api.md) - Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Eleven Music API > Eleven Music by ElevenLabs: a track from a description with or without vocals, music for your video and splitting a finished recording into stems. Developer: ElevenLabs Model key in the API: `elevenlabs_music` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2_5" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2_5", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2_5" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2_5" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Track from a description > A track from a text description, with or without vocals. A sound reference can be attached. Value of the mode field: `song` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What music is needed: genre, mood, instruments, tempo. Describe the voice here too, and give your own lyrics here naming their language. - Type: String - Minimum characters: 1 - Maximum characters: 4100 #### `model` (Optional) Model version: 2.5 is the newest, 2 is the previous one. The price is the same. - Type: String - Allowed values: `music_v2_5` (Version 2.5) - Default: `"music_v2_5"` #### `vocal` (Optional) With vocals or instrumental. With instrumental the model does not accept negative_prompt, seed, a sound reference or adherence other than high. - Type: String - Allowed values: `with_vocals` (With vocals), `instrumental` - Default: `"with_vocals"` #### `duration` (Optional) Track length in seconds, 10 to 600. The price grows with it. - Type: Integer - Minimum: 10 - Maximum: 600 - Default: `60` #### `style` (Optional) A ready style from the ElevenLabs library: the model keeps to its sound, the description sets the rest. none: no style. - Type: String - Allowed values: `none` (No style), `hrgo9qt4ebv9ondvrfby` (Percussive Rhythm), `myxkfft8fgqlknydgc9j` (Cinematic Ambient Atmosphere), `c8gueokxdvc0websp3mh` (Relaxing Ambient), `jhkwafhohc9agcda0cfr` (Whispery Angelic (Female)), `cmogtn8kgmqiog8dhexe` (Deep Hip-Hop Voice (Male)), `p1ywem2msdf5te27nvsq` (18th Century Symphony), `da3djkopsam0aiywt9pr` (Emotional Piano), `xiuhw6zlkhnmecbjoa1m` (Country), `vwseitetkxqcdgsmkp8q` (EDM Dance Pop (Female)), `pqqhd6miiqq1sck8hxpo` ('80s Nu-Disco Revival), `slmgjlsj7you9jtua7rs` (Bass Techno), `ycnbaxci6zvbfumryyjn` (Dark Cinematic), `iurf2sy9ee0sdcpenlxj` (Emo Trap Autotune (Male)), `ibgjl6wsy1m9zi7osp27` (Hard Rock (Male)), `p7uzmv4semqmck6dqlnh` (Hype Hip-Hop), `vs645jaw0kcr5ei0rsjv` (Deep House Groove), `pjrzgdgqqvyyukiukl7m` (High Energy House), `v1hamfp8dn8witowl0ku` (Golden Hour Indie Guitar), `aslj0pdvdods2agammwb` (Indie Dance), `rhesfql7yrkaaboxnxgp` (Angsty Alt Rock (Male)), `ojz144r6sblq1foezx1g` (Melancholic Indie (Male)), `rqjgx0tz2gjqz9bkewmb` (Jazz Hop), `sqwy9yr9rgik4fjq83lq` (Lofi Pulse), `etmjawmxfo7j0rhjoh9b` (Melodic House And Techno), `cba2y9ttpddnmakxzwps` (Metal), `voz6njhbsmhfoxlq4iiz` (Superhero Swell inspired by Stan Lee), `hs1ude6s5b5xecfqkeus` (Brazilian Funk), `kzyrnjd6p1wkctkwcndw` (Commercial Pop), `deg4quj3g28cbyuetrwl` (Power Pop (Male)), `gduoyhnzn5nvb246gg7i` (Upbeat Pop), `hzluexd1oy54d4g2rili` (Y2K RnB Pop (Female)), `suq4dir7rrlyldbl2hzq` (Reggaeton), `zhmmiqfkkv39avzbamxn` ('70s Cambodian Rock), `idlsxb9wbecwwrfdsctg` (Electronic Rock), `fc7ohoxr46pbtqmwpbub` (Gothic Power Rock (Female)), `el6hpw7kwoqvxf6xixct` (Peak Energy), `lh6n3z81aznqz0ohl9pn` (Rock Français), `mgvvvssqtnvoghqnciso` (Emo Trap), `tr9up85ilbll68sx8s7y` (Wooden Slit Drum), `vqipbdqc1msstidmcusy` (Afro House Beats), `isbeh7g7hu3yntwv25af` (Arabic Groove), `dnzdxqdeszfpxwry2pbe` (Baile Beats), `ymhinvkahlf4oath9qfu` (Golden Age Mambo inspired by Celia Cruz), `g6jrtolcvctpxfjtzt0b` (New York Salsa inspired by Celia Cruz), `psgsvdptlafmrwao54vr` (Retro Fanfare inspired by Stan Lee) - Default: `"none"` #### `title` (Optional) Track name: it goes into the caption and the file name. Not set: the model names the track. - Type: String - Maximum characters: 80 #### `negative_prompt` (Optional) What the music must not have, comma separated: no drums, no shouting. - Type: String - Maximum characters: 500 #### `adherence` (Optional) How strictly to follow the description: high almost literally, low as a mood. - Type: String - Allowed values: `high` (Strict), `medium`, `low` (Loose) - Default: `"high"` #### `seed` (Optional) Seed: with the same number and settings the result is similar, though not necessarily the same. Not set: a fresh take every time. - Type: Integer - Minimum: 0 - Maximum: 2147483647 #### `audio_urls` (Optional) Sound reference: one URL of a recording up to 30 seconds. The model takes instruments, sound, tempo and mood from it, the genre stays as described. Billed as generating the same length. - Type: List (String, uri) - Maximum items: 1 #### `reference_strength` (Optional) How strongly the reference drives the sound. No effect without a reference. - Type: String - Allowed values: `low`, `medium`, `high`, `xhigh` (Maximum) - Default: `"medium"` #### `output` (Optional) Format of the finished file: standard MP3, best quality MP3 or lossless WAV. It does not affect the price. - Type: String - Allowed values: `mp3_44100_192` (MP3, standard), `mp3_48000_320` (MP3, best), `pcm_44100` (WAV, lossless) - Default: `"mp3_44100_192"` #### `lyrics_file` (Optional) Attach the lyrics with timing as a separate LRC file: for subtitles and karaoke. - Type: Boolean - Default: `false` #### `ai_mark` (Optional) An invisible mark inside the file saying the music was made by AI. It does not change the sound and works with MP3 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - A sound reference is a URL of an MP3 or WAV file up to 50 MB and 30 seconds, sent as a whole. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio_urls` | Audio | mp3, wav | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A song from a description ```json { "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер" } } ``` Instrumental music ```json { "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Энергичная электроника для спортивного ролика, быстрый темп", "vocal": "instrumental", "duration": 30, "output": "pcm_44100" } } ``` A track from a sound reference ```json { "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Тёплый лоу-фай хип-хоп для учёбы, тихий мужской вокал", "audio_urls": [ "https://example.com/reference.mp3" ], "reference_strength": "high", "duration": 60 } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - An MP3 or WAV track. A song with lyrics also comes with the lyrics text, and on request with an LRC file of timed lyrics. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` or `document` | mp3, wav | 1 | WAV (output = pcm_44100) comes as a document. | | `document` | lrc | 0 or 1 | Timed lyrics: with lyrics_file = true, when the song has lyrics. | `result.texts`: The lyrics, when the song has any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.lrc", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Music for a video > Background music for your video: length and mood follow the picture. The music here never has singing. Value of the mode field: `video` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What music the video needs: mood, genre, instruments. - Type: String - Minimum characters: 1 - Maximum characters: 1000 #### `model` (Optional) Model version: 2.5 is the newest, 2 is the previous one. The price is the same. - Type: String - Allowed values: `music_v2_5` (Version 2.5) - Default: `"music_v2_5"` #### `video_urls` (Required) One URL of the video. The music length and the price come from the video. - Type: List (String, uri) - Maximum items: 1 #### `tags` (Optional) Words about the sound, comma separated, up to 10: metal, orchestra, fast tempo. The model already sees the plot in the video. - Type: String - Maximum characters: 200 #### `title` (Optional) Music name: it goes into the caption and the names of the video and music files. Not set: the files are named music. - Type: String - Maximum characters: 80 #### `output` (Optional) Format of the finished file: MP3 or lossless WAV. ElevenLabs gives no best quality MP3 in this mode. It does not affect the price. - Type: String - Allowed values: `mp3_44100_192` (MP3, standard), `pcm_44100` (WAV, lossless) - Default: `"mp3_44100_192"` #### `ai_mark` (Optional) An invisible mark inside the file saying the music was made by AI. It does not change the sound and works with MP3 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of an MP4 file up to 200 MB and 10 minutes, sent as a whole. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4 | 1 | 200 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Music for a video ```json { "model": "elevenlabs_music", "settings": { "mode": "video", "prompt": "Лёгкая вдохновляющая музыка для ролика о путешествии", "tags": "акустика, струнные, светлое настроение", "video_urls": [ "https://example.com/trip.mp4" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Your video with the new music and the same music as a separate MP3 or WAV file. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | Your video with the new music. | | `audio` or `document` | mp3, wav | 1 | The same music on its own, WAV comes as a document. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Split into stems > A finished recording is split into separate stems: vocals, drums, bass and the rest. Value of the mode field: `stems` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `audio_urls` (Required) One URL of the recording to split. The price follows its length. - Type: List (String, uri) - Maximum items: 1 #### `stems` (Optional) Two stems: vocals and all the other music. Six: vocals, drums, bass, guitar, keys and the rest. Six cost twice as much as two. - Type: String - Allowed values: `two_stems_v1` (Two stems), `six_stems_v1` (Six stems) - Default: `"two_stems_v1"` #### `output` (Optional) Format of the finished file: MP3 or lossless WAV. ElevenLabs gives no best quality MP3 in this mode. It does not affect the price. - Type: String - Allowed values: `mp3_44100_192` (MP3, standard), `pcm_44100` (WAV, lossless) - Default: `"mp3_44100_192"` #### `ai_mark` (Optional) An invisible mark inside the file saying the music was made by AI. It does not change the sound and works with MP3 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The recording is a URL of an MP3 file up to 50 MB and 10 minutes, sent as a whole. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio_urls` | Audio | mp3 | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Vocals apart from the music ```json { "model": "elevenlabs_music", "settings": { "mode": "stems", "audio_urls": [ "https://example.com/song.mp3" ], "stems": "two_stems_v1" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A ZIP archive with every stem as a separate file in the chosen format. | Kind | Formats | How many | Note | |---|---|---|---| | `document` | zip | 1 | Inside, every stem is a separate MP3 or WAV file. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "document", "filename": "result.zip", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Eleven Music: features and prices](https://api.cyhub.ai/models/eleven-music) - Other versions: [Eleven Music v2 API](https://api.cyhub.ai/en/models/eleven-music-v2/api.md) - Similar models: [Suno V6 API](https://api.cyhub.ai/en/models/suno/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Eleven Music v2 API > Eleven Music v2 by ElevenLabs: a track from a description with or without vocals and background music for your video. Tracks up to 10 minutes, and you can attach a sound reference. Developer: ElevenLabs Model key in the API: `elevenlabs_music` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## Track from a description > A track from a text description, with or without vocals. A sound reference can be attached. Value of the mode field: `song` This page is about Eleven Music v2: send model = music_v2. Without the model field the task runs on music_v2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What music is needed: genre, mood, instruments, tempo. Describe the voice here too, and give your own lyrics here naming their language. - Type: String - Minimum characters: 1 - Maximum characters: 4100 #### `model` (Optional) Model version: 2.5 is the newest, 2 is the previous one. The price is the same. - Type: String - Allowed values: `music_v2` (Version 2) - Default: `"music_v2_5"` #### `vocal` (Optional) With vocals or instrumental. With instrumental the model does not accept negative_prompt, seed, a sound reference or adherence other than high. - Type: String - Allowed values: `with_vocals` (With vocals), `instrumental` - Default: `"with_vocals"` #### `duration` (Optional) Track length in seconds, 10 to 600. The price grows with it. - Type: Integer - Minimum: 10 - Maximum: 600 - Default: `60` #### `style` (Optional) A ready style from the ElevenLabs library: the model keeps to its sound, the description sets the rest. none: no style. - Type: String - Allowed values: `none` (No style), `hrgo9qt4ebv9ondvrfby` (Percussive Rhythm), `myxkfft8fgqlknydgc9j` (Cinematic Ambient Atmosphere), `c8gueokxdvc0websp3mh` (Relaxing Ambient), `jhkwafhohc9agcda0cfr` (Whispery Angelic (Female)), `cmogtn8kgmqiog8dhexe` (Deep Hip-Hop Voice (Male)), `p1ywem2msdf5te27nvsq` (18th Century Symphony), `da3djkopsam0aiywt9pr` (Emotional Piano), `xiuhw6zlkhnmecbjoa1m` (Country), `vwseitetkxqcdgsmkp8q` (EDM Dance Pop (Female)), `pqqhd6miiqq1sck8hxpo` ('80s Nu-Disco Revival), `slmgjlsj7you9jtua7rs` (Bass Techno), `ycnbaxci6zvbfumryyjn` (Dark Cinematic), `iurf2sy9ee0sdcpenlxj` (Emo Trap Autotune (Male)), `ibgjl6wsy1m9zi7osp27` (Hard Rock (Male)), `p7uzmv4semqmck6dqlnh` (Hype Hip-Hop), `vs645jaw0kcr5ei0rsjv` (Deep House Groove), `pjrzgdgqqvyyukiukl7m` (High Energy House), `v1hamfp8dn8witowl0ku` (Golden Hour Indie Guitar), `aslj0pdvdods2agammwb` (Indie Dance), `rhesfql7yrkaaboxnxgp` (Angsty Alt Rock (Male)), `ojz144r6sblq1foezx1g` (Melancholic Indie (Male)), `rqjgx0tz2gjqz9bkewmb` (Jazz Hop), `sqwy9yr9rgik4fjq83lq` (Lofi Pulse), `etmjawmxfo7j0rhjoh9b` (Melodic House And Techno), `cba2y9ttpddnmakxzwps` (Metal), `voz6njhbsmhfoxlq4iiz` (Superhero Swell inspired by Stan Lee), `hs1ude6s5b5xecfqkeus` (Brazilian Funk), `kzyrnjd6p1wkctkwcndw` (Commercial Pop), `deg4quj3g28cbyuetrwl` (Power Pop (Male)), `gduoyhnzn5nvb246gg7i` (Upbeat Pop), `hzluexd1oy54d4g2rili` (Y2K RnB Pop (Female)), `suq4dir7rrlyldbl2hzq` (Reggaeton), `zhmmiqfkkv39avzbamxn` ('70s Cambodian Rock), `idlsxb9wbecwwrfdsctg` (Electronic Rock), `fc7ohoxr46pbtqmwpbub` (Gothic Power Rock (Female)), `el6hpw7kwoqvxf6xixct` (Peak Energy), `lh6n3z81aznqz0ohl9pn` (Rock Français), `mgvvvssqtnvoghqnciso` (Emo Trap), `tr9up85ilbll68sx8s7y` (Wooden Slit Drum), `vqipbdqc1msstidmcusy` (Afro House Beats), `isbeh7g7hu3yntwv25af` (Arabic Groove), `dnzdxqdeszfpxwry2pbe` (Baile Beats), `ymhinvkahlf4oath9qfu` (Golden Age Mambo inspired by Celia Cruz), `g6jrtolcvctpxfjtzt0b` (New York Salsa inspired by Celia Cruz), `psgsvdptlafmrwao54vr` (Retro Fanfare inspired by Stan Lee) - Default: `"none"` #### `title` (Optional) Track name: it goes into the caption and the file name. Not set: the model names the track. - Type: String - Maximum characters: 80 #### `negative_prompt` (Optional) What the music must not have, comma separated: no drums, no shouting. - Type: String - Maximum characters: 500 #### `adherence` (Optional) How strictly to follow the description: high almost literally, low as a mood. - Type: String - Allowed values: `high` (Strict), `medium`, `low` (Loose) - Default: `"high"` #### `seed` (Optional) Seed: with the same number and settings the result is similar, though not necessarily the same. Not set: a fresh take every time. - Type: Integer - Minimum: 0 - Maximum: 2147483647 #### `audio_urls` (Optional) Sound reference: one URL of a recording up to 30 seconds. The model takes instruments, sound, tempo and mood from it, the genre stays as described. Billed as generating the same length. - Type: List (String, uri) - Maximum items: 1 #### `reference_strength` (Optional) How strongly the reference drives the sound. No effect without a reference. - Type: String - Allowed values: `low`, `medium`, `high`, `xhigh` (Maximum) - Default: `"medium"` #### `output` (Optional) Format of the finished file: standard MP3, best quality MP3 or lossless WAV. It does not affect the price. - Type: String - Allowed values: `mp3_44100_192` (MP3, standard), `mp3_48000_320` (MP3, best), `pcm_44100` (WAV, lossless) - Default: `"mp3_44100_192"` #### `lyrics_file` (Optional) Attach the lyrics with timing as a separate LRC file: for subtitles and karaoke. - Type: Boolean - Default: `false` #### `ai_mark` (Optional) An invisible mark inside the file saying the music was made by AI. It does not change the sound and works with MP3 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - A sound reference is a URL of an MP3 or WAV file up to 50 MB and 30 seconds, sent as a whole. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `audio_urls` | Audio | mp3, wav | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A song from a description ```json { "model": "elevenlabs_music", "settings": { "mode": "song", "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря", "duration": 90, "title": "Летний вечер", "model": "music_v2" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - An MP3 or WAV track. A song with lyrics also comes with the lyrics text, and on request with an LRC file of timed lyrics. | Kind | Formats | How many | Note | |---|---|---|---| | `audio` or `document` | mp3, wav | 1 | WAV (output = pcm_44100) comes as a document. | | `document` | lrc | 0 or 1 | Timed lyrics: with lyrics_file = true, when the song has lyrics. | `result.texts`: The lyrics, when the song has any. A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [ "Text of the result, for example lyrics" ], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.lrc", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## Music for a video > Background music for your video: length and mood follow the picture. The music here never has singing. Value of the mode field: `video` This page is about Eleven Music v2: send model = music_v2. Without the model field the task runs on music_v2_5. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `prompt` (Required) What music the video needs: mood, genre, instruments. - Type: String - Minimum characters: 1 - Maximum characters: 1000 #### `model` (Optional) Model version: 2.5 is the newest, 2 is the previous one. The price is the same. - Type: String - Allowed values: `music_v2` (Version 2) - Default: `"music_v2_5"` #### `video_urls` (Required) One URL of the video. The music length and the price come from the video. - Type: List (String, uri) - Maximum items: 1 #### `tags` (Optional) Words about the sound, comma separated, up to 10: metal, orchestra, fast tempo. The model already sees the plot in the video. - Type: String - Maximum characters: 200 #### `title` (Optional) Music name: it goes into the caption and the names of the video and music files. Not set: the files are named music. - Type: String - Maximum characters: 80 #### `output` (Optional) Format of the finished file: MP3 or lossless WAV. ElevenLabs gives no best quality MP3 in this mode. It does not affect the price. - Type: String - Allowed values: `mp3_44100_192` (MP3, standard), `pcm_44100` (WAV, lossless) - Default: `"mp3_44100_192"` #### `ai_mark` (Optional) An invisible mark inside the file saying the music was made by AI. It does not change the sound and works with MP3 only. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. > The API sets these settings itself, do not send them: `files_as_is` = `true` ### Input - The video is a URL of an MP4 file up to 200 MB and 10 minutes, sent as a whole. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_urls` | Video | mp4 | 1 | 200 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. Music for a video ```json { "model": "elevenlabs_music", "settings": { "mode": "video", "prompt": "Лёгкая вдохновляющая музыка для ролика о путешествии", "tags": "акустика, струнные, светлое настроение", "video_urls": [ "https://example.com/trip.mp4" ], "model": "music_v2" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - Your video with the new music and the same music as a separate MP3 or WAV file. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | Your video with the new music. | | `audio` or `document` | mp3, wav | 1 | The same music on its own, WAV comes as a document. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "audio", "filename": "audio.mp3", "size": 4194304, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Eleven Music v2: features and prices](https://api.cyhub.ai/models/eleven-music-v2) - Other versions: [Eleven Music API](https://api.cyhub.ai/en/models/eleven-music/api.md) - Similar models: [Suno V6 API](https://api.cyhub.ai/en/models/suno/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Tripo 3D API > Tripo 3D models from a description, from one photo or from several views of an object. Model key in the API: `tripo3d` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A model from a text description, no pictures. Value of the task_type field: `text_to_model` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v3.1-20260211` (v3.1), `P1-20260311` (P1 (low-poly)) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `prompt` (Required) What object is needed. Any language works. - Type: String - Minimum characters: 1 - Maximum characters: 1024 #### `negative_prompt` (Optional) What must not be in the model. - Type: String - Maximum characters: 255 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from a description ```json { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From a photo > A model from one photo of an object. Best with a clean background and the whole object. Value of the task_type field: `image_to_model` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v3.1-20260211` (v3.1), `P1-20260311` (P1 (low-poly)) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `image_url` (Required) One URL of a photo of the object. - Type: List (String, uri) - Maximum items: 1 #### `texture_alignment` (Optional) How the texture is laid: closer to the photo or closer to the shape of the model. - Type: String - Allowed values: `original_image` (Match the image), `geometry` - Default: `"original_image"` #### `enable_image_autofix` (Optional) Improve the photo first for a better result. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_url` | Images | jpeg, jpg, png | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from a photo ```json { "model": "tripo3d", "settings": { "task_type": "image_to_model", "image_url": [ "https://example.com/chair.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From several views > A model from several photos of one object from different sides: the most accurate shape. Needs the front photo and at least one more, each in the field of its side. The sides are the object's own: left_url takes the photo where it faces left. If the sides are swapped, the model may get a second front instead of a back. Value of the task_type field: `multiview_to_model` ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v3.1-20260211` (v3.1), `P1-20260311` (P1 (low-poly)) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `front_url` (Required) Photo of the object from the front. Required. - Type: List (String, uri) - Maximum items: 1 #### `left_url` (Optional) Photo of the object's left side: the object faces left in the photo, a character shows its left arm to the camera. - Type: List (String, uri) - Maximum items: 1 #### `back_url` (Optional) Photo of the object from the back. - Type: List (String, uri) - Maximum items: 1 #### `right_url` (Optional) Photo of the object's right side: the object faces right in the photo, a character shows its right arm to the camera. - Type: List (String, uri) - Maximum items: 1 #### `texture_alignment` (Optional) How the texture is laid: closer to the photo or closer to the shape of the model. - Type: String - Allowed values: `original_image` (Match the image), `geometry` - Default: `"original_image"` #### `enable_image_autofix` (Optional) Improve the photo first for a better result. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `front_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `left_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `back_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `right_url` | Images | jpeg, jpg, png | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from the front and back photos ```json { "model": "tripo3d", "settings": { "task_type": "multiview_to_model", "front_url": [ "https://example.com/front.png" ], "back_url": [ "https://example.com/back.png" ] } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Tripo 3D: features and prices](https://api.cyhub.ai/models/tripo-3d) - Other versions: [Tripo 3.0 API](https://api.cyhub.ai/en/models/tripo-3-0/api.md), [Tripo 2.5 API](https://api.cyhub.ai/en/models/tripo-2-5/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Tripo 3.0 API > Tripo 3.0 3D models from a description, from one photo or from several views of an object. Maximum detail and every setting. Model key in the API: `tripo3d` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v3.0-20250812" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v3.0-20250812", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v3.0-20250812" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v3.0-20250812" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A model from a text description, no pictures. Value of the task_type field: `text_to_model` This page is about Tripo 3.0: send model_version = v3.0-20250812. Without the model_version field the task runs on v3.1-20260211. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v3.0-20250812` (v3.0) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `prompt` (Required) What object is needed. Any language works. - Type: String - Minimum characters: 1 - Maximum characters: 1024 #### `negative_prompt` (Optional) What must not be in the model. - Type: String - Maximum characters: 255 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from a description ```json { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v3.0-20250812" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From a photo > A model from one photo of an object. Best with a clean background and the whole object. Value of the task_type field: `image_to_model` This page is about Tripo 3.0: send model_version = v3.0-20250812. Without the model_version field the task runs on v3.1-20260211. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v3.0-20250812` (v3.0) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `image_url` (Required) One URL of a photo of the object. - Type: List (String, uri) - Maximum items: 1 #### `texture_alignment` (Optional) How the texture is laid: closer to the photo or closer to the shape of the model. - Type: String - Allowed values: `original_image` (Match the image), `geometry` - Default: `"original_image"` #### `enable_image_autofix` (Optional) Improve the photo first for a better result. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_url` | Images | jpeg, jpg, png | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from a photo ```json { "model": "tripo3d", "settings": { "task_type": "image_to_model", "image_url": [ "https://example.com/chair.png" ], "model_version": "v3.0-20250812" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From several views > A model from several photos of one object from different sides: the most accurate shape. Needs the front photo and at least one more, each in the field of its side. The sides are the object's own: left_url takes the photo where it faces left. If the sides are swapped, the model may get a second front instead of a back. Value of the task_type field: `multiview_to_model` This page is about Tripo 3.0: send model_version = v3.0-20250812. Without the model_version field the task runs on v3.1-20260211. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v3.0-20250812` (v3.0) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `front_url` (Required) Photo of the object from the front. Required. - Type: List (String, uri) - Maximum items: 1 #### `left_url` (Optional) Photo of the object's left side: the object faces left in the photo, a character shows its left arm to the camera. - Type: List (String, uri) - Maximum items: 1 #### `back_url` (Optional) Photo of the object from the back. - Type: List (String, uri) - Maximum items: 1 #### `right_url` (Optional) Photo of the object's right side: the object faces right in the photo, a character shows its right arm to the camera. - Type: List (String, uri) - Maximum items: 1 #### `texture_alignment` (Optional) How the texture is laid: closer to the photo or closer to the shape of the model. - Type: String - Allowed values: `original_image` (Match the image), `geometry` - Default: `"original_image"` #### `enable_image_autofix` (Optional) Improve the photo first for a better result. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `front_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `left_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `back_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `right_url` | Images | jpeg, jpg, png | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from the front and back photos ```json { "model": "tripo3d", "settings": { "task_type": "multiview_to_model", "front_url": [ "https://example.com/front.png" ], "back_url": [ "https://example.com/back.png" ], "model_version": "v3.0-20250812" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Tripo 3.0: features and prices](https://api.cyhub.ai/models/tripo-3-0) - Other versions: [Tripo 3D API](https://api.cyhub.ai/en/models/tripo-3d/api.md), [Tripo 2.5 API](https://api.cyhub.ai/en/models/tripo-2-5/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en) --- # Tripo 2.5 API > Tripo 2.5 3D models from a description, from one photo or from several views of an object. The previous stable version, some settings are not available in it. Model key in the API: `tripo3d` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v2.5-20250123" } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v2.5-20250123", }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v2.5-20250123" } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v2.5-20250123" } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now ## From a description > A model from a text description, no pictures. Value of the task_type field: `text_to_model` This page is about Tripo 2.5: send model_version = v2.5-20250123. Without the model_version field the task runs on v3.1-20260211. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v2.5-20250123` (v2.5) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `prompt` (Required) What object is needed. Any language works. - Type: String - Minimum characters: 1 - Maximum characters: 1024 #### `negative_prompt` (Optional) What must not be in the model. - Type: String - Maximum characters: 255 Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from a description ```json { "model": "tripo3d", "settings": { "task_type": "text_to_model", "prompt": "Деревянный сундук с железными уголками", "texture_quality": "standard", "model_version": "v2.5-20250123" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From a photo > A model from one photo of an object. Best with a clean background and the whole object. Value of the task_type field: `image_to_model` This page is about Tripo 2.5: send model_version = v2.5-20250123. Without the model_version field the task runs on v3.1-20260211. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v2.5-20250123` (v2.5) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `image_url` (Required) One URL of a photo of the object. - Type: List (String, uri) - Maximum items: 1 #### `texture_alignment` (Optional) How the texture is laid: closer to the photo or closer to the shape of the model. - Type: String - Allowed values: `original_image` (Match the image), `geometry` - Default: `"original_image"` #### `enable_image_autofix` (Optional) Improve the photo first for a better result. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `image_url` | Images | jpeg, jpg, png | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from a photo ```json { "model": "tripo3d", "settings": { "task_type": "image_to_model", "image_url": [ "https://example.com/chair.png" ], "model_version": "v2.5-20250123" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## From several views > A model from several photos of one object from different sides: the most accurate shape. Needs the front photo and at least one more, each in the field of its side. The sides are the object's own: left_url takes the photo where it faces left. If the sides are swapped, the model may get a second front instead of a back. Value of the task_type field: `multiview_to_model` This page is about Tripo 2.5: send model_version = v2.5-20250123. Without the model_version field the task runs on v3.1-20260211. ### Parameters Model parameters go inside settings. Omitted optional fields take their default values. #### `model_version` (Optional) Model version. v3.1 and v3.0 are the most detailed and have every setting. v2.5 and P1 lack some settings, P1 is for low-poly models. - Type: String - Allowed values: `v2.5-20250123` (v2.5) - Default: `"v3.1-20260211"` #### `texture` (Optional) A textured model. Without it, only the shape. - Type: Boolean - Default: `true` #### `pbr` (Optional) Realistic materials with reflections and highlights. Turns the texture on too. - Type: Boolean - Default: `true` #### `texture_quality` (Optional) Texture quality. HD is more detailed and costs more. HD is available only in versions v3.1, v3.0 and P1. - Type: String - Allowed values: `standard`, `detailed` - Default: `"standard"` #### `geometry_quality` (Optional) Shape quality. Ultra is more detailed, slower and costs more, only in v3.1 and v3.0. - Type: String - Allowed values: `standard`, `detailed` (Ultra (maximum detail)) - Default: `"standard"` #### `face_limit` (Optional) How many polygons the model has. Not set: chosen automatically. The allowed range depends on the version and settings: 50 to 20,000 for P1, 500 to 20,000 for smart low-poly. - Type: Integer - Minimum: 48 - Maximum: 2000000 #### `auto_size` (Optional) Scale the model to real-world size in meters. Available only in versions v3.1, v3.0 and P1. - Type: Boolean - Default: `false` #### `orientation` (Optional) Rotation of the finished model: the usual one or as in the source photo. Works only for a model from a photo or from several views, and only with a texture. - Type: String - Allowed values: `default`, `align_image` (Align with image) - Default: `"default"` #### `quad` (Optional) A model made of quads, easier to edit and animate. The file will be FBX. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `smart_low_poly` (Optional) A low-poly model with a clean mesh. Best for simple objects. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `generate_parts` (Optional) A model made of separate parts. Does not combine with texture, PBR, quads or smart low-poly. Available only in versions v3.1 and v3.0. - Type: Boolean - Default: `false` #### `front_url` (Required) Photo of the object from the front. Required. - Type: List (String, uri) - Maximum items: 1 #### `left_url` (Optional) Photo of the object's left side: the object faces left in the photo, a character shows its left arm to the camera. - Type: List (String, uri) - Maximum items: 1 #### `back_url` (Optional) Photo of the object from the back. - Type: List (String, uri) - Maximum items: 1 #### `right_url` (Optional) Photo of the object's right side: the object faces right in the photo, a character shows its right arm to the camera. - Type: List (String, uri) - Maximum items: 1 #### `texture_alignment` (Optional) How the texture is laid: closer to the photo or closer to the shape of the model. - Type: String - Allowed values: `original_image` (Match the image), `geometry` - Default: `"original_image"` #### `enable_image_autofix` (Optional) Improve the photo first for a better result. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ### Input - Photos are URLs of JPEG or PNG files up to 20 MB. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `front_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `left_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `back_url` | Images | jpeg, jpg, png | 1 | 20 MB | | `right_url` | Images | jpeg, jpg, png | 1 | 20 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ### Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. A model from the front and back photos ```json { "model": "tripo3d", "settings": { "task_type": "multiview_to_model", "front_url": [ "https://example.com/front.png" ], "back_url": [ "https://example.com/back.png" ], "model_version": "v2.5-20250123" } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ### Output - A GLB 3D model file (FBX with quads) and a preview picture. - Generation takes several minutes. | Kind | Formats | How many | Note | |---|---|---|---| | `image` | png, jpg, webp | 0 or 1 | A preview picture of the model, when Tripo sends one. | | `document` | glb, fbx | 1 | The 3D model file: FBX with quad = true, GLB otherwise. | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "image", "filename": "image.png", "size": 1843200, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" }, { "index": 1, "kind": "document", "filename": "result.glb", "size": 2097152, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [Tripo 2.5: features and prices](https://api.cyhub.ai/models/tripo-2-5) - Other versions: [Tripo 3D API](https://api.cyhub.ai/en/models/tripo-3d/api.md), [Tripo 3.0 API](https://api.cyhub.ai/en/models/tripo-3-0/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en)